Reference

Semantic schemas and constraints

Behavior

Input	Constraint	Result
Contract with one customer	Exactly one `customer` relation	Conforms
Contract missing an effective date	Required `effective_date` property	Violation at that property
`purchased` from Policy to Product	Domain must be Customer	Type violation

How it works

KnowledgeSchema is an optional validation value alongside Mari’s graph model. It describes a small set of concept, property, and relation checks. Validation returns every violation with the focus object and constraint identifier. The caller decides whether that report blocks a write, requests repair, or is ignored.

Define a backend-neutral semantic contract

from mari_components.schema import (
    ConceptType,
    KnowledgeSchema,
    PropertyConstraint,
    RelationConstraint,
    validate_records,
)

schema = KnowledgeSchema(
    schema_id="commerce",
    version="2",
    concepts=(ConceptType("Customer"), ConceptType("Contract"), ConceptType("Product")),
    properties=(PropertyConstraint(
        "Contract", "effective_date", required=True,
        value_type="string", value_format="date",
    ),),
    relations=(RelationConstraint("purchased", source="Customer", target="Product"),),
    allow_unknown_properties=False,
)

report = validate_records(schema, records)
if not report.conforms:
    for violation in report.violations:
        print(violation.focus_id, violation.constraint_id)

Function definitions and options

Value / function	Options	Meaning
`PropertyConstraint`	`required`, `minimum_count`, `maximum_count`	Independent cardinality checks
`PropertyConstraint`	`value_type`	Empty, string, integer, number, boolean, object, or array
`PropertyConstraint`	`value_format`	Empty, ISO date, or timezone-aware ISO date-time. Formats require strings
`KnowledgeSchema`	`allow_unknown_properties`	Defaults true for open-world compatibility. False reports undeclared properties
`validate_records`	Schema, records, optional relations	Reports duplicate IDs, concepts, properties, types, cardinality, and relation domain/range

Boolean values fail integer and number constraints, and non-finite floats fail number constraints. These are explicit scalar checks. Mari leaves values such as "14" unchanged during validation.

Caller-written adapters can translate this utility to formats such as LinkML and JSON Schema. SHACL and RDF/OWL integrations can use the same values. SQL DDL or property-graph constraints need their own mapping. The application controls schema choice, URI meaning, and its node and edge representation.

Version the schema alongside any extraction or validation recipe that consumes it. A source revision can stay unchanged as a schema update changes its validation result. Model that schema version as an explicit dependency in dependency-aware updates.

Measures

Layer	Measure
Constraint engine	Conformance against hand-labeled valid and invalid records
Adapter	Round-trip preservation of required/cardinality/domain/range semantics
Migration	Violations introduced and records requiring transformation
Extraction	Schema-valid precision and recall of proposed entities/relations

Papers, standards, and implementations

SHACL Recommendation OWL 2 overview LinkML pySHACL Shape Expressions

LinkML and pySHACL are Apache-2.0 references. Mari implements a small common constraint kernel and leaves standards-complete validation to adapters.