Read bindings
Connect model terms to concrete data and control how they resolve
A read binding connects one ontology term to a workspace data endpoint and describes how the term is read. It belongs to a project and selects a compiled package/version, term kind, read method, resolution and access policy. It does not create a pipeline or write records.
Methods and compatible endpoints
| Method | Compatible endpoint | Resolution |
|---|---|---|
| Virtual | Supported readable table, query, stream or API | Class identity field; property/relationship source field |
| Materialized | ontology_fact_store | Read stored entities, values, relationships and identities |
| Asserted | ontology_fact_store is required by binding validation | Select assertion statuses, confidence, validity and conflict behavior |
| Inferred | Supported readable endpoint or fact store | Input aliases mapped to terms, plus CEL expression |
Asserted values are read from project assertion records. Their endpoint/package context still must satisfy the binding contract; creating an asserted binding does not send assertions into that fact store. An inferred output depends on other bindings and does not create its own entity population.
Example: live order identity
You need a Semogram account, project binding authoring permission, the compiled operations model, and a readable endpoint containing entity_id values such as https://example.com/orders/1. The identity field must be stable and unique for this class. The endpoint uses the installed Postgres read capability for a table source; connection credentials belong to that installation.
Open Ontology → Bindings → New binding. Select the compiled package and actual numeric version, Data endpoint, Business term https://example.com/operations#Order, Term identifier with the same IRI, Applies to Class, Read method Virtual, Status Active, Expected values Many. Enter {"entity_id_field":"entity_id"} in Resolution. Review validation and save.
Bind the Order class https://example.com/operations#Order to entity_id in the selected live orders endpoint. Use the actual compiled package/version and an active virtual class binding. Show validation, identity mapping and access policy before saving.Use a workspace API key with bindings:write. Set SEMOGRAM_API_KEY in your shell and replace UUID placeholders with accessible resource IDs.
curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_UUID>/ontology/read-bindings" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Idempotency-Key: <UNIQUE_OPERATION_KEY>" \
--header "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"ontologyPackageId": "<COMPILED_PACKAGE_UUID>",
"ontologyPackageVersion": 1,
"termRef": "https://example.com/operations#Order",
"termIri": "https://example.com/operations#Order",
"termKind": "class",
"kind": "virtual",
"dataEndpointId": "<SOURCE_ENDPOINT_UUID>",
"status": "active",
"cardinality": "many",
"resolution": {
"entity_id_field": "entity_id"
}
}
JSON{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "ontology_read_binding_create",
"arguments": {
"projectId": "<PROJECT_UUID>",
"binding": {
"ontologyPackageId": "<COMPILED_PACKAGE_UUID>",
"ontologyPackageVersion": 1,
"termRef": "https://example.com/operations#Order",
"termIri": "https://example.com/operations#Order",
"termKind": "class",
"kind": "virtual",
"dataEndpointId": "<SOURCE_ENDPOINT_UUID>",
"status": "active",
"cardinality": "many",
"resolution": {
"entity_id_field": "entity_id"
}
},
"idempotencyKey": "<UNIQUE_BINDING_KEY>"
}
}
}The complete first example supplies its own database fixture and all four bindings; no hidden records are required.
How a query chooses a binding
Only Active bindings participate. Resolution prefers an exact term over *, an exact term kind over *, then non-default bindings, lower numeric priority and newer binding version; remaining ties have stable ordering. The root class must match the query's base read kind. Output terms can resolve through other methods, including inferred dependencies.
A default wildcard materialized binding can provide coverage for a fact store. It does not replace a more specific binding, provide virtual field mappings, or establish that facts exist. Review the actual resolved binding IDs in query results.
Cardinality and missing values
One expects one value, Optional one permits absence, Many permits a collection, Unknown leaves the expectation unspecified. Scalar disagreements are not safely resolved by picking the first row. Configure supported conflict behavior for assertions or fix the data/binding when values are ambiguous.
Access policy
Bindings can require permissions or workspace roles and apply supported masks: none, redact, hash, tokenize or last4. Keyed masks require server configuration. Policy is evaluated for the actual caller; an API key does not automatically inherit a human owner's role. Inferred outputs inherit restrictions from dependencies rather than exposing masked values indirectly.
Validate the binding's endpoint contract and resolution, then run a known query under the intended caller. Configuration validation alone does not prove data freshness, completeness or external-system access.