The Service-STEM API is a microservice that generates accessible text content and images from MathML markup. The service follows the Nordic MathML Guidelines to ensure proper accessibility and compliance with mathematical content standards.
http://[HOST]:[PORT]
No authentication is required for this service.
GET /health
Returns the health status of the service.
Response:
{
"name": "service-stem",
"version": "2.0.0",
"timestamp": "2024-01-15T10:30:00.000Z"
}POST /detect-version
Analyzes MathML content to detect version and compatibility issues.
Request Body:
{
"content": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\">...</math>"
}Response:
{
"success": true,
"versionInfo": {
"version": "2.0.0",
"isLegacy": false,
"legacyFeatures": [],
"migrationHints": [],
"compatibilityMode": false
},
"recommendations": [],
"timestamp": "2024-01-15T10:30:00.000Z"
}POST /migrate
Migrates legacy MathML content to the new format.
Request Body:
{
"content": "<m:math xmlns:m=\"http://www.w3.org/1998/Math/MathML\">...</m:math>"
}Response:
{
"success": true,
"originalContent": "<m:math xmlns:m=\"http://www.w3.org/1998/Math/MathML\">...</m:math>",
"migratedContent": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\">...</math>",
"versionInfo": {
"version": "2.0.0",
"isLegacy": true,
"legacyFeatures": ["m: namespace prefix"],
"migrationHints": ["Replace m: namespace with direct xmlns declaration"]
},
"migrationResult": {
"changes": ["Replaced m: namespace with direct xmlns"],
"warnings": [],
"success": true
},
"validationResult": {
"isValid": true,
"errors": [],
"warnings": [],
"remainingLegacyFeatures": []
},
"recommendations": [],
"timestamp": "2024-01-15T10:30:00.000Z"
}POST /
Processes MathML content and returns accessible text representations.
Request Body:
{
"contentType": "math",
"content": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\">...</math>"
}Query Parameters:
noImage(optional): ALIX threshold for image generation (default: 25)noEquationText(optional): ALIX threshold for equation text (default: 12)
Response:
{
"success": true,
"input": {
"mathml": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\">...</math>"
},
"output": {
"text": {
"words": ["3", "minus", "2", "equals", "1"],
"translated": "3 minus 2 equals 1",
"latex": "3-2=1",
"ascii": "3-2=1",
"html": "<div class=\"math-content\">...</div>"
},
"image": {
"path": null
},
"attributes": {
"language": "en",
"alix": 15,
"alixThresholdNoImage": 25,
"alixThresholdNoEquationText": 12
}
}
}Required: All MathML content must use the direct namespace declaration:
<math xmlns="http://www.w3.org/1998/Math/MathML">Deprecated: The m: namespace prefix is no longer supported:
<!-- DEPRECATED - Do not use -->
<m:math xmlns:m="http://www.w3.org/1998/Math/MathML">Migration: Use the /migrate endpoint to automatically convert legacy content:
curl -H 'Content-Type: application/json' \
-d '{ "content": "<m:math xmlns:m=\"http://www.w3.org/1998/Math/MathML\"><m:mn>3</m:mn><m:mo>+</m:mo><m:mn>2</m:mn></m:math>" }' \
-X POST \
http://[HOST]:[PORT]/migrateThe display attribute controls how mathematical expressions are rendered:
inline(default): Expression appears within textblock: Expression appears as a separate block
<!-- Inline math (default) -->
<math xmlns="http://www.w3.org/1998/Math/MathML">
<mn>3</mn><mo>+</mo><mn>2</mn>
</math>
<!-- Block math -->
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
<mn>3</mn><mo>+</mo><mn>2</mn><mo>=</mo><mn>5</mn>
</math>Important: The <math> element should never be a standalone block element. Always place it within a paragraph element or equivalent.
Specify the language using the xml:lang attribute:
<math xmlns="http://www.w3.org/1998/Math/MathML" xml:lang="en">
<mn>3</mn><mo>+</mo><mn>2</mn>
</math>Supported languages: en, no, da, sv, fi, nl, nn
Numbers:
<mn>3</mn> <!-- Number -->
<mn>3.14</mn> <!-- Decimal -->
<mn>-5</mn> <!-- Negative number -->Variables:
<mi>x</mi> <!-- Variable -->
<mi>y</mi> <!-- Variable -->
<mi>α</mi> <!-- Greek letter -->Operators:
<mo>+</mo> <!-- Plus -->
<mo>-</mo> <!-- Minus -->
<mo>=</mo> <!-- Equals -->
<mo>(</mo> <!-- Opening parenthesis -->
<mo>)</mo> <!-- Closing parenthesis -->The Nordic MathML Guidelines specify invisible operators for unambiguous mathematical expressions:
<!-- Invisible multiplication -->
<mo>⁢</mo>
<!-- Invisible function application -->
<mo>⁡</mo>
<!-- Invisible plus -->
<mo>⁤</mo>
<!-- Invisible comma -->
<mo>⁣</mo>Examples:
<!-- 3x (invisible multiplication) -->
<mn>3</mn><mo>⁢</mo><mi>x</mi>
<!-- f(x) (invisible function application) -->
<mi>f</mi><mo>⁡</mo><mo>(</mo><mi>x</mi><mo>)</mo>
<!-- 100 m (number with unit) -->
<mn>100</mn><mo>⁢</mo><mi mathvariant="normal">m</mi>Use proper Unicode characters for mathematical symbols:
<!-- Minus sign (not hyphen) -->
<mo>−</mo>
<!-- Prime -->
<mo>′</mo>
<!-- Element of -->
<mo>∈</mo>
<!-- Greek letters -->
<mi>α</mi> <!-- alpha -->
<mi>β</mi> <!-- beta -->
<mi>γ</mi> <!-- gamma -->Chemical formulas:
<!-- H₂O -->
<msub><mi>H</mi><mn>2</mn></msub><mi>O</mi>
<!-- CO₂ -->
<mi>C</mi><msub><mi>O</mi><mn>2</mn></msub>
<!-- Isotope notation -->
<mmultiscripts>
<mi>C</mi>
<mn>14</mn>
<none/>
<mn>6</mn>
</mmultiscripts>Use <mtable> for labeled equations:
<mtable>
<mtr>
<mtd><mn>3</mn><mo>+</mo><mn>2</mn><mo>=</mo><mn>5</mn></mtd>
<mtd><mo>(</mo><mn>1</mn><mo>)</mo></mtd>
</mtr>
</mtable>Use <menclose> for crossed out mathematical expressions:
<menclose notation="updiagonalstrike">
<mn>3</mn><mo>+</mo><mn>2</mn>
</menclose>Use Unicode symbol 鄉 (⎕) for blank spaces:
<mn>3</mn><mo>+</mo><mi>鄉</mi><mo>=</mo><mn>5</mn>Use mathvariant="normal" for units:
<mn>100</mn><mo>⁢</mo><mi mathvariant="normal">m</mi>
<mn>50</mn><mo>⁢</mo><mi mathvariant="normal">km/h</mi>The following elements are deprecated and will cause validation errors:
<mfenced>- Use<mo>elements for parentheses instead<semantics>- Not required unless specifically requested<annotation>- Not required unless specifically requested<annotation-xml>- Not required unless specifically requested
The following attributes are deprecated and will generate warnings:
alttext- MathML support has improved, making this unnecessaryaltimg- MathML support has improved, making this unnecessary
When MathML validation fails, the service returns a 400 status with detailed error information:
{
"success": false,
"error": "MathML validation failed",
"validationErrors": [
"Deprecated element <mfenced> is not allowed. Use <mo> elements for parentheses instead."
],
"validationWarnings": [
"alttext attribute is deprecated. MathML support has improved and this attribute should not be used."
]
}- 400: Invalid request (missing content, validation errors)
- 500: Internal server error
- 501: Unsupported content type
curl -H 'Content-Type: application/json' \
-d '{
"contentType": "math",
"content": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\" xml:lang=\"en\"><mn>3</mn><mo>+</mo><mn>2</mn><mo>=</mo><mn>5</mn></math>"
}' \
-X POST \
http://localhost:3000/curl -H 'Content-Type: application/json' \
-d '{
"content": "<m:math xmlns:m=\"http://www.w3.org/1998/Math/MathML\"><m:mn>3</m:mn><m:mo>+</m:mo><m:mn>2</m:mn></m:math>"
}' \
-X POST \
http://localhost:3000/detect-versioncurl -H 'Content-Type: application/json' \
-d '{
"content": "<m:math xmlns:m=\"http://www.w3.org/1998/Math/MathML\"><m:mn>3</m:mn><m:mo>+</m:mo><m:mn>2</m:mn></m:math>"
}' \
-X POST \
http://localhost:3000/migratecurl -H 'Content-Type: application/json' \
-d '{
"contentType": "math",
"content": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\" display=\"block\"><mn>3</mn><mo>⁢</mo><mi>x</mi><mo>+</mo><mn>2</mn><mo>⁢</mo><mi>y</mi><mo>=</mo><mn>10</mn></math>"
}' \
-X POST \
http://localhost:3000/curl -H 'Content-Type: application/json' \
-d '{
"contentType": "math",
"content": "<math xmlns=\"http://www.w3.org/1998/Math/MathML\"><msub><mi>H</mi><mn>2</mn></msub><mi>O</mi></math>"
}' \
-X POST \
http://localhost:3000/- Always use the direct namespace declaration -
xmlns="http://www.w3.org/1998/Math/MathML" - Use invisible operators for unambiguous mathematical expressions
- Use proper Unicode characters for mathematical symbols
- Specify language using
xml:langattribute - Use
display="block"only for standalone mathematical expressions - Avoid deprecated elements and attributes
- Place
<math>elements within paragraph elements - never as standalone blocks - Use
mathvariant="normal"for units and non-mathematical text
No rate limiting is currently implemented.
For issues and questions related to the Nordic MathML Guidelines, please refer to the official documentation or contact the Nordic agencies.