Skip to main content

Validator API

Semantic Treehouse exposes an API for programmatic message validation. This enables integration with CI/CD pipelines, automated testing, and external tooling without needing the web interface.

Base URL: https://your-community.semantic-treehouse.nl/api/v2/evalidator

Authentication​

All requests require an API key passed in the Access-Token header. The key must belong to an account with the Validator API Consumer role.

Access-Token: YOUR_API_KEY

Contact your Semantic Treehouse administrator to obtain an API key.

Endpoints​

Get available validators​

GET /api/v2/evalidator/info

Returns the list of projects, specifications, versions, and syntax bindings that have validation enabled. Use this to discover which syntaxBindingId to pass to the validate endpoint.

Example request:

curl "https://your-sth.semantic-treehouse.nl/api/v2/evalidator/info" \
  -H "Access-Token: YOUR_API_KEY"

Response structure:

{
  "projects": [
    {
      "id": "...",
      "name": "My Project",
      "specifications": [
        {
          "id": "...",
          "name": "Invoice",
          "specVersions": [
            {
              "id": "...",
              "version": "1.0",
              "fullLabel": "Invoice 1.0",
              "syntaxBindings": [
                {
                  "id": "abc-123",
                  "name": "UBL 2.1 XML",
                  "syntaxType": "XML",
                  "validatorEnabled": true,
                  "includeGeneratedSchema": true,
                  "validateSchema": true,
                  "validateBusinessRules": true,
                  "validateCodelists": false,
                  "updatedAt": "2025-03-15T10:30:00+00:00"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "maxUploadSize": "16M"
}

Validate a message​

POST /api/v2/evalidator/syntax/{syntaxBindingId}/validate

Validates a message against the configured schema and business rules for the given syntax binding.

Request:

  • Body: the raw message content (XML, JSON, or RDF depending on syntax type).
  • Content-Type: should match the message format (e.g., application/xml, application/json).
  • Query parameter skipSchematronIds (optional): a comma-separated list of Schematron IDs to skip during validation.

Example request:

curl -X POST \
  "https://your-sth.semantic-treehouse.nl/api/v2/evalidator/syntax/abc-123/validate" \
  -H "Access-Token: YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  -d @invoice.xml

Response:

{
  "syntax_valid": true,
  "schema_valid": true,
  "business_rules_valid": false,
  "syntax_errors": {
    "error": [],
    "warning": []
  },
  "schema_errors": {
    "error": [
      {
        "level": "error",
        "code": "cvc-complex-type.2.4.a",
        "line": 15,
        "column": 42,
        "message": "Invalid content was found starting with element 'cac:Unknown'.",
        "lineText": "    <cac:Unknown>value</cac:Unknown>"
      }
    ],
    "warning": []
  },
  "business_rules_report": {
    "error": [
      {
        "ruleId": "NL-R-001",
        "context": "/Invoice",
        "count": 1,
        "violations": [
          {
            "fpi": "NL-R-001",
            "flag": "fatal",
            "location": "/Invoice[1]",
            "test": "exists(cac:BillingReference)",
            "message": "A credit note from a Dutch supplier MUST contain a billing reference.",
            "xml": "<!-- XML snippet around the violation -->",
            "lineNr": 12,
            "see": "https://example.com/rule-docs/NL-R-001"
          }
        ]
      }
    ],
    "warning": [],
    "notice": [],
    "info": [],
    "debug": []
  },
  "svrl_reports": ["...raw SVRL XML..."],
  "original_request": null
}

Validation report fields​

FieldTypeDescription
syntax_validbooleanWhether the message is well-formed (parseable).
schema_validboolean or nullWhether the message passes structural schema validation. null if schema validation is disabled.
business_rules_validboolean or nullWhether the message passes all Schematron rules. null if business rule validation is disabled.
syntax_errorsobjectParse errors, grouped by severity (error, warning). Each error has the same structure as schema_errors entries.
schema_errorsobjectSchema validation issues, grouped by severity. Each issue includes level, code, line, column, message, and lineText.
business_rules_reportobjectSchematron results, grouped by severity (error, warning, notice, info, debug). Each entry contains ruleId, context, count, and a violations array. Each violation includes fpi, flag, location, test, message, xml (snippet around the violation), lineNr, and see (documentation link).
svrl_reportsstring[]Raw SVRL (Schematron Validation Report Language) XML output for advanced consumers.
original_requeststring or nullThe raw request body, echoed back. Currently null for XML validation.

Skipping Schematron rules​

To skip specific Schematron rule sets during validation, pass their IDs (obtained from the /info endpoint) as a comma-separated query parameter:

POST /api/v2/evalidator/syntax/abc-123/validate?skipSchematronIds=sch-456,sch-789

This is useful when you want to validate against the schema but exclude certain business rule sets that are not applicable to your use case.

See also​