Patch reference (Strixonomy v0.27)¶

Status: Documents behavior in Strixonomy v0.27.0. Pre-1.0 APIs may change. Canonical feature list: What ships today.

Start here: smallest patch¶

Change a label on Turtle with a bare JSON array (most callers use this — CLI --file / LSP patches):

[
  {
    "op": "set_label",
    "entity_iri": "http://example.org/people#Person",
    "value": "Human"
  }
]

# Preview, then apply (point at your ontology folder / First success tutorial)
strixonomy patch /path/to/strixonomy-tutorial/example.ttl --file label.json --preview
strixonomy patch /path/to/strixonomy-tutorial/example.ttl --file label.json
strixonomy validate /path/to/strixonomy-tutorial

More samples: Sample patches. Full op tables below.

Patch write-back uses a JSON array of patch operations. The CLI (strixonomy patch) and LSP (strixonomy/applyAxiomPatch) accept the same envelope; operation sets differ by file extension.

Supported formats: Turtle (.ttl), OBO (.obo), RDF/XML (.owl/.rdf), OWL/XML (.owx). XML uses full-document re-serialize (ADR-0021). See Supported formats.

Optional transaction envelope (v0.20+): inbound patches may be wrapped as { "transaction": { "changes": [...] } }. Most callers still pass a bare JSON array.

Source of truth: patch.rs on GitHub

Format¶

• JSON array of operation objects
• Each object has an "op" field (snake_case)
• Turtle (.ttl), OBO (.obo), RDF/XML (.owl/.rdf), and OWL/XML (.owx) documents (dispatch by extension)

Turtle operations¶

Turtle operations (v0.22 OWL 2 construct coverage)¶

SWRL operations (v0.24)¶

SWRL rules are stored as ontology annotations (strixonomy:swrlRule JSON). Prefer the Rule Browser / Rule Editor in VS Code for interactive authoring; use patches for CI and scripts.

rule_json is a string containing a JSON object with body / head atoms (optional id, enabled). Example atom shape:

{
  "op": "add_swrl_rule",
  "ontology_iri": "http://example.org/people",
  "rule_json": "{\"id\":\"person-is-human\",\"body\":[{\"kind\":\"class\",\"class\":\"http://example.org/people#Person\",\"arg\":{\"variable\":\"x\"}}],\"head\":[{\"kind\":\"class\",\"class\":\"http://example.org/people#Human\",\"arg\":{\"variable\":\"x\"}}],\"enabled\":true}"
}

See SWRL cookbook. LSP helpers: strixonomy/listSwrlRules, strixonomy/validateSwrlRule, strixonomy/parseSwrlRule (LSP API).

OBO operations (.obo)¶

See ADR-0019. Ops use term_id (OBO id, e.g. GO:0008150).

RDF/XML and OWL/XML operations (.owl / .rdf / .owx)¶

Same Turtle-shaped PatchOp JSON applies via Horned load → mutate → full-document re-serialize (v0.21+). Prefixed ops and XML-unsupported edge cases return structured errors and leave the file unchanged. Details: OWL/XML write-back.

kind values for create_entity¶

class, object_property, data_property, annotation_property, individual, datatype

Examples¶

Create a class with label and parent¶

[
  {
    "op": "create_entity",
    "entity_iri": "http://example.org/people#Employee",
    "kind": "class"
  },
  {
    "op": "add_label",
    "entity_iri": "http://example.org/people#Employee",
    "value": "Employee"
  },
  {
    "op": "add_sub_class_of",
    "entity_iri": "http://example.org/people#Employee",
    "parent_iri": "http://example.org/people#Person"
  }
]

Add a HasKey¶

[
  {
    "op": "add_has_key",
    "class_iri": "http://example.org/keys#Person",
    "properties": ["http://example.org/keys#hasSSN"]
  }
]

Add an import¶

[
  {
    "op": "add_import",
    "ontology_iri": "http://example.org/people",
    "import_iri": "http://purl.obolibrary.org/obo/ro.owl"
  }
]

Property domain and characteristic¶

[
  {
    "op": "add_domain",
    "entity_iri": "http://example.org/people#worksFor",
    "class_iri": "http://example.org/people#Person"
  },
  {
    "op": "set_functional",
    "entity_iri": "http://example.org/people#worksFor",
    "value": true
  }
]

Rename via label (not IRI rename)¶

[
  {
    "op": "set_label",
    "entity_iri": "http://example.org/people#Person",
    "value": "knows"
  }
]

Mark deprecated and delete¶

[
  {
    "op": "set_deprecated",
    "entity_iri": "http://example.org/people#LegacyClass",
    "value": true
  }
]

[
  {
    "op": "delete_entity",
    "entity_iri": "http://example.org/people#LegacyClass"
  }
]

Complex subclass (Manchester)¶

[
  {
    "op": "add_complex_sub_class_of",
    "entity_iri": "http://example.org/clinic#Patient",
    "manchester": "ex:hasRecord some ex:MedicalRecord"
  }
]

Equivalent class (Manchester)¶

[
  {
    "op": "set_equivalent_class",
    "entity_iri": "http://example.org/clinic#Staff",
    "manchester": "ex:Employee"
  }
]

Disjoint classes¶

[
  {
    "op": "add_disjoint_class",
    "entity_iri": "http://example.org/org#Cat",
    "other_iri": "http://example.org/org#Dog"
  }
]

CLI usage¶

# Preview changes (stdout JSON, no write)
strixonomy patch ./ontology.ttl patches.json --preview

# Apply patches
strixonomy patch ./ontology.ttl patches.json

# Validate after apply
strixonomy validate .

Response shape (ApplyPatchResult)¶

{
  "applied": true,
  "preview_text": "...",
  "diagnostics": [],
  "document_path": "/path/to/ontology.ttl"
}

• applied: true when changes were written (false for --preview or on error)
• preview_text: resulting Turtle text when content changed
• diagnostics: patch errors (non-empty means apply failed)

LSP usage¶

Method: strixonomy/applyAxiomPatch

{
  "document_uri": "file:///path/to/ontology.ttl",
  "patches": [
    { "op": "add_label", "entity_iri": "http://ex#Person", "value": "Human" }
  ],
  "preview_only": false
}

See lsp-api.md and authoring.md.

Limitations (v0.27)¶

• Write-back: Turtle (.ttl), OBO (.obo), RDF/XML (.owl/.rdf), OWL/XML (.owx); JSON-LD and line-oriented RDF are read-only. XML is semantic re-serialize — OWL/XML write-back
• OBO: patch ops edit an existing term_id — there is no create-term / new-stanza op (create terms in the file or via other tools, then patch)
• Prefix manager ops are Turtle-only; XML write-back returns a clear error
• Simple add_sub_class_of parent must be a named class IRI; use Manchester ops (add_complex_sub_class_of, add_equivalent_class, etc.) for class expressions
• XML axiom annotations cover the same axiom_op set as Turtle (sub_class_of, domain/range, property hierarchy / inverse / equiv / disjoint, same/different individuals, …). Identity is named-entity based; supply related_iri when multiple axioms match. Annotation values may be Simple literals or IRIs (<iri> / absolute URL)
• Datatype definitions accept Manchester DataRanges (xsd:integer[>= 0], {…}, and/or/not) on Turtle and XML
• Catalog getEntity lists HasKey, DisjointUnion, RBox/ABox families, datatype definitions, and nested axiom annotations on axiom cards
• Manchester coverage includes restriction constructors (some/only/min/max/exactly, not, value, Self, one-of, data facets) — see SHIPPED Manchester scope
• Patch engine uses targeted text edits on Turtle/OBO; unusual formatting may need manual review. XML always full-document re-serialize.