JSON Schema & Validation

OLS v1.0 is validatable. Every file must declare a schema, version, and type.

{
  "$schema": "https://ols.otyg.org/schema/v1.0/corpus.schema.json",
  "ols_version": "1.0.0",
  "type": "corpus"
}

Validation Layers

Validation should happen in a predictable order:

1. Parse JSON and reject malformed syntax.
2. Select the schema declared by $schema.
3. Validate required fields and value shapes.
4. Verify that ols_version is supported and type matches the schema.
5. Resolve IDs and references across the package.
6. Apply active profile constraints, authority rules, and deterministic behavior checks.

JSON Schema catches structural errors, but it cannot by itself prove that a reference exists, a calendar tie is resolved, a rubric transition is possible, or content has ecclesial approval.

{
  "$schema": "https://ols.otyg.org/schema/v1.0/reading.schema.json",
  "ols_version": "1.0.0",
  "type": "reading",
  "id": "reading-john-1-1-17"
}

Use the schema for the actual file type. A manifest, reading, section, and complete corpus should not all claim corpus.schema.json merely because they are distributed together.

LocalizedText Schema

The LocalizedText type is the foundation for all human-readable text fields. Validators MUST enforce:

• The text object MUST contain at least one entry.
• Each key MUST be a valid BCP 47 language tag.
• Each value MUST be a non-empty string.

{
  "$id": "https://ols.otyg.org/schema/v1.1/localized-text.schema.json",
  "type": "object",
  "required": ["text"],
  "properties": {
    "text": {
      "type": "object",
      "minProperties": 1,
      "patternProperties": {
        "^[a-z]{2,3}(-[A-Za-z]{4})?(-[A-Z]{2})?$": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "variants": { "$ref": "#/$defs/TranslationVariantsMap" },
    "textMeta": { "$ref": "#/$defs/TextMeta" }
  },
  "$defs": {
    "TranslationVariantsMap": {
      "type": "object",
      "description": "Map of language tags to arrays of translation variant objects.",
      "patternProperties": {
        "^[a-z]{2,3}(-[A-Za-z]{4})?(-[A-Z]{2})?$": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/TranslationVariant" }
        }
      },
      "additionalProperties": false
    },
    "TranslationVariant": {
      "type": "object",
      "required": ["value"],
      "properties": {
        "value": { "type": "string", "minLength": 1 },
        "label": { "type": "string", "minLength": 1 },
        "source": { "type": "string" },
        "default": { "type": "boolean" },
        "register": { "type": "string", "enum": ["liturgical", "scholarly", "pastoral", "catechetical", "devotional"] },
        "audience": { "type": "string", "enum": ["general", "academic", "children", "neophyte"] }
      },
      "additionalProperties": false
    },
    "TextMeta": {
      "type": "object",
      "properties": {
        "direction": { "type": "string", "enum": ["ltr", "rtl"] },
        "register": { "type": "string" },
        "translationType": { "type": "string", "enum": ["formal", "dynamic", "paraphrase", "literal", "liturgical"] },
        "readingLevel": { "type": "string" },
        "alignment": { "type": "string" },
        "containsSacredName": { "type": "boolean" }
      },
      "additionalProperties": false
    }
  }
}

Translation Variants Validation Rules

Validators implementing OLS v1.1+ MUST enforce the following rules on TranslationVariantsMap:

Rule ID	Severity	Description
OLS_VARIANT_LANG_MISMATCH	error	Every language key in variants MUST also exist in text.
OLS_VARIANT_EMPTY_ARRAY	error	A language entry in variants MUST contain at least one variant object.
OLS_VARIANT_VALUE_REQUIRED	error	Every variant object MUST have a non-empty value field.
OLS_VARIANT_MULTI_DEFAULT	error	At most one variant per language MAY be marked "default": true.
OLS_VARIANT_DEFAULT_SYNC	error	If a variant is marked "default": true, its value MUST exactly equal the corresponding text entry for that language.
OLS_VARIANT_NO_DUPLICATES	warning	Two variants in the same language SHOULD NOT have identical value strings.
OLS_VARIANT_LABEL_RECOMMENDED	info	Variants SHOULD include a label for UI display purposes.
OLS_VARIANT_SOURCE_RECOMMENDED	info	Variants SHOULD include a source for provenance tracking.

Utterance Validation Rules

Utterance objects carry additional validation requirements:

Rule ID	Severity	Description
OLS_UTT_ID_REQUIRED	error	Every utterance MUST have a unique id matching pattern ^ut-[a-z0-9-]+$.
OLS_UTT_ROLE_REF	error	Every entry in roles MUST reference a declared role id in the corpus.
OLS_UTT_MODE_VALID	error	The mode field MUST be one of: spoken, chanted, sung, whispered, silent, canticle, responsive, recited.
OLS_UTT_TEXT_REQUIRED	error	The text field MUST be present and contain at least one language entry.
OLS_UTT_VARIANT_INTEGRITY	error	If variants is present on an utterance, all Translation Variants validation rules apply.