diff --git a/src/oold/validation/frame.py b/src/oold/validation/frame.py index be315b7..2e712df 100644 --- a/src/oold/validation/frame.py +++ b/src/oold/validation/frame.py @@ -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"): @@ -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. @@ -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) @@ -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. @@ -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: @@ -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, {}))) ] @@ -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 diff --git a/tests/test_validation/test_jsonld.py b/tests/test_validation/test_jsonld.py index 5b50052..7d1518e 100644 --- a/tests/test_validation/test_jsonld.py +++ b/tests/test_validation/test_jsonld.py @@ -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 @@ -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 = "" + nq = "\n".join([ + f" {rdf_type} .", + f"_:c {rdf_type} .", + "_:c .", + '_:c "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"], @@ -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). @@ -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 = "" + nq = "\n".join([ + f" {rdf_type} .", + f"_:c {rdf_type} .", + "_:c .", + '_:c "Fe" .', + f"_:m {rdf_type} .", + "_:m .", + '_:m "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(): @@ -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():