Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 75 additions & 9 deletions src/oold/validation/frame.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,14 +41,17 @@
def is_embed(node: Any) -> bool:
"""True when a property's schema describes an embedded *object* value.

A ``$ref`` alone is not enough: it may point at a scalar DataType leaf, which is a literal
rather than an embed. After dereferencing, a real embed is inlined as an object with its own
properties anyway, so the object shape is the reliable signal.
After dereferencing an embed is inlined as an object with its own properties, so the object
shape is the primary signal. On an undereferenced schema it is a ``$ref``, which therefore
counts too. A ``$ref`` pointing at a scalar DataType leaf is a literal rather than an embed,
but it costs only an empty subframe, and framing leaves a literal value alone.
"""
if not isinstance(node, dict):
return False
if node.get("type") == "object" and node.get("properties"):
return True
if isinstance(node.get("$ref"), str):
return True
if node.get("items") is not None:
return is_embed(node["items"])
for keyword in ("anyOf", "oneOf", "allOf"):
Expand Down Expand Up @@ -97,6 +100,25 @@ def embedded_properties(schema: dict[str, Any]) -> list[str]:
return list(dict.fromkeys([*structural, *scoped]))


def pinned_type_default(schema: Any) -> list[str] | None:
"""The instance type a schema pins through ``properties.type.default``.

``OOLD-INS-4b5c`` only fires where ``x-oold-instance-rdf-type`` is declared, so pinning the
type as a default on the ``@type``-aliased property is a permitted spelling, and the frame
needs that anchor as much as it needs the keyword's.
"""
if not isinstance(schema, dict):
return None
properties = schema.get("properties")
declaration = properties.get("type") if isinstance(properties, dict) else None
default = declaration.get("default") if isinstance(declaration, dict) else None
if isinstance(default, str):
return [default]
if isinstance(default, list) and default and all(isinstance(entry, str) for entry in default):
return list(default)
return None


def instance_rdf_types(schema: Any) -> list[str] | None:
"""The instance ``rdf:type``(s) a schema declares, most-derived-wins.

Expand All @@ -105,12 +127,18 @@ def instance_rdf_types(schema: Any) -> list[str] | None:
inference rather than being materialised. A subclass that wants supertypes in the data lists
them explicitly. After dereferencing the most-derived value sits at the top level; the
``allOf`` walk is the fallback for a subclass that omits its own declaration.

``properties.type.default`` is read where the keyword is absent, and it is read before the
``allOf`` walk, because a schema's own spelling of its type is nearer than an inherited one.
"""
if not isinstance(schema, dict):
return None
own = schema.get("x-oold-instance-rdf-type")
if isinstance(own, list) and own:
return own
pinned = pinned_type_default(schema)
if pinned:
return pinned
if isinstance(schema.get("allOf"), list):
for sub in schema["allOf"]:
types = instance_rdf_types(sub)
Expand Down Expand Up @@ -162,6 +190,22 @@ def _is_reference_term(definition: Any) -> bool:
return definition.get("@type") == "@id" or "@reverse" in definition


def reverse_predicates(schema: dict[str, Any]) -> dict[str, list[str]]:
"""The reverse IRI each reverse-mapped property compacts to, keyed by that IRI.

Several terms may share one reverse IRI, since nothing stops a schema from naming the same
relation twice. The IRI is taken as the term writes it, compact or absolute: the frame
resolves it against the same context the term was read from.
"""
properties = collect_composed_properties(schema)
grouped: dict[str, list[str]] = {}
for name, definition in context_terms(schema.get("@context")).items():
predicate = definition.get("@reverse")
if name in properties and isinstance(predicate, str):
grouped.setdefault(predicate, []).append(name)
return grouped


def reference_properties(schema: dict[str, Any]) -> list[str]:
"""Properties whose value is a reference, so framing must leave it an IRI.

Expand All @@ -173,8 +217,9 @@ def reference_properties(schema: dict[str, Any]) -> list[str]:
(JSON-LD 1.1 4.1.10), so ``"@type": "@id"`` beside it is redundant and authors omit it;
keying only on ``@type`` misses the idiomatic spelling and embeds the targets.

Embedding takes precedence where a property carries both: a property shaped like an object
is an embed whatever its term says.
Embedding takes precedence where a property carries both, and the test is membership in
:func:`embedded_properties` rather than the shape alone, so the two lists cannot both claim a
property that embeds through a scoped ``@context``.
"""

def is_reference(node: Any) -> bool:
Expand All @@ -195,11 +240,12 @@ def is_reference(node: Any) -> bool:
properties = collect_composed_properties(schema)
terms = context_terms(schema.get("@context"))
aliases = keyword_alias_keys(schema)
embedded = set(embedded_properties(schema))
return [
name
for name, prop in properties.items()
if name not in aliases
and not is_embed(prop)
and name not in embedded
and (is_reference(prop) or _is_reference_term(terms.get(name, {})))
]

Expand All @@ -210,14 +256,34 @@ def schema_to_frame(schema: dict[str, Any], context_ref: Any = _UNSET) -> dict[s
``context_ref``, when given, is used as the frame's ``@context`` in place of the schema's
inline one. Pass the schema's URL so the document loader resolves inherited and scoped
contexts rather than losing them.

The reference subframes are written before the embedded ones, so a property both lists claim
keeps the ``{}`` that preserves its nested keys.

A reverse-mapped property is written under ``@reverse``, by its reverse IRI rather than by its
term name. Term names expand, so two terms sharing one reverse IRI would otherwise produce two
subframes under that IRI; a frame must be a single object, and a processor rejects the pair.
"""
frame: dict[str, Any] = {"@embed": "@once"}
frame["@context"] = schema.get("@context") if context_ref is _UNSET else context_ref
types = instance_rdf_types(schema)
if types:
frame["@type"] = types[0] if len(types) == 1 else types
for name in embedded_properties(schema):
frame[name] = {}

predicate_of = {name: predicate for predicate, names in reverse_predicates(schema).items() for name in names}
grouped: dict[str, dict[str, Any]] = {}

def place(name: str, subframe: dict[str, Any]) -> None:
predicate = predicate_of.get(name)
if predicate is None:
frame[name] = subframe
else:
grouped[predicate] = subframe

for name in reference_properties(schema):
frame[name] = {"@embed": "@never"}
place(name, {"@embed": "@never"})
for name in embedded_properties(schema):
place(name, {})
if grouped:
frame["@reverse"] = grouped
return frame
137 changes: 135 additions & 2 deletions tests/test_validation/test_jsonld.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
is_embed,
keyword_alias_keys,
reference_properties,
reverse_predicates,
schema_to_frame,
)
from oold.validation.loader import DocumentLoader, describe_jsonld_error
Expand Down Expand Up @@ -98,6 +99,61 @@ def test_instance_rdf_types_is_most_derived_wins():
assert instance_rdf_types({"type": "object"}) is None


def test_a_type_pinned_as_a_default_anchors_the_frame():
"""OO-LD/oold-python#177.

Without an anchor the root is only the frame root while every edge runs forward; the first
backwards edge leaves nothing matched and framing returns a bare ``@graph``.
"""
context = {
"ex": "https://example.org/",
"obo": "http://purl.obolibrary.org/obo/",
"id": "@id",
"type": {"@id": "@type", "@container": "@set"},
"Material": "ex:Material",
"components": "ex:components",
"chemical_composition": {"@reverse": "obo:RO_0000080"},
}
schema = {
"type": "object",
"@context": context,
"properties": {
"type": {"type": "array", "items": {"type": "string"}, "default": ["Material"]},
"chemical_composition": {"type": "object", "properties": {"components": {}}},
},
}
assert instance_rdf_types(schema) == ["Material"]
frame = schema_to_frame(schema)
assert frame["@type"] == "Material"

rdf_type = "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"
nq = "\n".join([
f"<https://example.org/m1> {rdf_type} <https://example.org/Material> .",
f"_:c {rdf_type} <https://example.org/ChemicalComposition> .",
"_:c <http://purl.obolibrary.org/obo/RO_0000080> <https://example.org/m1> .",
'_:c <https://example.org/components> "Fe" .',
"",
])
graph = jsonld.from_rdf(nq, {"format": "application/n-quads", "useNativeTypes": True})
framed = jsonld.frame(graph, frame, {"omitDefault": True})

assert "@graph" not in framed
assert framed["chemical_composition"]["components"] == "Fe"


def test_the_keyword_wins_over_a_type_pinned_as_a_default():
schema = {
"x-oold-instance-rdf-type": ["ex:B"],
"properties": {"type": {"default": ["ex:A"]}},
}
assert instance_rdf_types(schema) == ["ex:B"]
# A schema's own default is nearer than a type inherited through allOf.
assert instance_rdf_types({
"allOf": [{"x-oold-instance-rdf-type": ["ex:A"]}],
"properties": {"type": {"default": ["ex:B"]}},
}) == ["ex:B"]


def test_schema_to_frame_carries_type_context_and_subframes():
schema = {
"x-oold-instance-rdf-type": ["schema:Person"],
Expand Down Expand Up @@ -175,6 +231,35 @@ def test_embedding_wins_where_a_property_carries_both_signals():
assert reference_properties(schema) == []


def test_a_ref_valued_embed_keeps_its_subframe_before_dereferencing():
"""OO-LD/oold-python#175.

``$ref`` is the only trace of the embed while the schema is undereferenced, and the
``"@type": "@id"`` that OO-LD requires on such a term makes it look reference-valued at the
same time. With both lists claiming it, ``{}`` was overwritten by ``@embed: @never`` and the
framed node came back empty.
"""
schema = {
"type": "object",
"@context": {
"type": {"@id": "@type", "@container": "@set"},
"chemical_composition": {
"@id": "https://example.org/chemical_composition",
"@type": "@id",
"@context": "ChemicalComposition.schema.json",
},
},
"properties": {
"type": {"type": "array", "items": {"type": "string"}, "default": ["Material"]},
"chemical_composition": {"$ref": "ChemicalComposition.schema.json"},
},
}
assert is_embed({"$ref": "ChemicalComposition.schema.json"})
assert embedded_properties(schema) == ["chemical_composition"]
assert reference_properties(schema) == []
assert schema_to_frame(schema, "Material.schema.json")["chemical_composition"] == {}


def test_a_bare_reverse_term_is_reference_valued():
"""A reverse term's values are node references by definition (JSON-LD 1.1 4.1.10).

Expand All @@ -187,7 +272,55 @@ def test_a_bare_reverse_term_is_reference_valued():
"properties": {"employees": {"type": "array", "items": {"type": "string"}}},
}
assert reference_properties(schema) == ["employees"]
assert schema_to_frame(schema)["employees"] == {"@embed": "@never"}
assert schema_to_frame(schema)["@reverse"] == {"schema:worksFor": {"@embed": "@never"}}


def test_two_terms_on_one_reverse_iri_share_a_single_subframe():
"""OO-LD/oold-python#176.

Term names expand, so a subframe per term became two subframes under one IRI. A frame must be
a single object, and pyld raised ``invalid frame`` with ``{'frame': [{}, {}]}``.
"""
context = {
"ex": "https://example.org/",
"obo": "http://purl.obolibrary.org/obo/",
"id": "@id",
"type": {"@id": "@type", "@container": "@set"},
"Material": "ex:Material",
"components": "ex:components",
"chemical_composition": {"@reverse": "obo:RO_0000080"},
"material_composition": {"@reverse": "obo:RO_0000080"},
}
schema = {
"x-oold-instance-rdf-type": ["ex:Material"],
"type": "object",
"@context": context,
"properties": {
"chemical_composition": {"type": "object", "properties": {"components": {}}},
"material_composition": {"type": "object", "properties": {"components": {}}},
},
}
assert reverse_predicates(schema) == {"obo:RO_0000080": ["chemical_composition", "material_composition"]}
frame = schema_to_frame(schema)
assert frame["@reverse"] == {"obo:RO_0000080": {}}
assert "chemical_composition" not in frame

rdf_type = "<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"
nq = "\n".join([
f"<https://example.org/m1> {rdf_type} <https://example.org/Material> .",
f"_:c {rdf_type} <https://example.org/ChemicalComposition> .",
"_:c <http://purl.obolibrary.org/obo/RO_0000080> <https://example.org/m1> .",
'_:c <https://example.org/components> "Fe" .',
f"_:m {rdf_type} <https://example.org/MaterialComposition> .",
"_:m <http://purl.obolibrary.org/obo/RO_0000080> <https://example.org/m1> .",
'_:m <https://example.org/components> "steel" .',
"",
])
graph = jsonld.from_rdf(nq, {"format": "application/n-quads", "useNativeTypes": True})
framed = jsonld.frame(graph, frame, {"omitDefault": True})

compositions = framed["chemical_composition"]
assert sorted(entry["components"] for entry in compositions) == ["Fe", "steel"]


def test_a_keyword_alias_never_gets_a_subframe():
Expand Down Expand Up @@ -234,7 +367,7 @@ def test_schema_to_frame_keeps_reference_valued_properties_as_iris():
}
frame = schema_to_frame(schema, "Organization.schema.json")
assert frame["address"] == {}
assert frame["employees"] == {"@embed": "@never"}
assert frame["@reverse"] == {"schema:worksFor": {"@embed": "@never"}}


def test_framing_leaves_a_reference_whose_target_has_triples_as_an_iri():
Expand Down
Loading