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",
        "fpi": "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, fpi (the rule identifier as known to users, such as the business rule identifier), 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​