Read unsupported vocabulary properties by IRI

.agents/skills/add-vocab/SKILL.md

@@ -63,6 +63,12 @@ The `@fedify/vocab-tools` snapshots are stored separately for Deno, Node.js,
 and Bun.  Always update all three with the aggregate task when generated output
 changes; do not update only one runtime's snapshot.
 
+Adding a property also changes what `getRawPropertyValues()` returns for its
+IRI and for its `redundantProperties` aliases: they stop being retained as
+unsupported properties and are encoded from the typed values instead.  Mention
+this in the changelog entry when applications may already be reading the
+property through that function.
+
 
 YAML file format
 ----------------

CHANGES.md

@@ -277,6 +277,15 @@ To be released.
     plugin rules as errors, so projects generated by `fedify init` exclude the
     selected rule while keeping the deprecated option usable.
     [[#1335], [#1340]]
+ -  Added the `raw-property-iri-invalid` rule, which reports property IRIs
+    passed to `getRawPropertyValues()` and `getRawPropertyValue()` that throw
+    at runtime, such as terms and JSON-LD keywords, and compact IRIs such as
+    `as:content`, which are looked up literally.  With ESLint and Oxlint, the
+    `modules` option adds other vocabulary modules generated by
+    `@fedify/vocab-tools` to the default `@fedify/vocab`.  [[#1272], [#1356]]
+
+[#1272]: https://github.com/fedify-dev/fedify/issues/1272
+[#1356]: https://github.com/fedify-dev/fedify/pull/1356
 
 ### @fedify/postgres
 
@@ -310,6 +319,17 @@ To be released.
     entries may not be visited.  Accessor and serialization traversal costs are
     unchanged.  [[#1243], [#1337]]
 
+ -  Added `getRawPropertyValues()` and `getRawPropertyValue()` functions,
+    which read a property of a vocabulary object by its full IRI and return
+    its values in expanded JSON-LD.  They let applications read properties
+    that Fedify has no accessor for, such as an extension used by only a few
+    peers, without depending on the JSON-LD serialization cache: unknown
+    properties are now retained when an object is decoded, including embedded
+    objects, and survive `clone()` and `deepClone()`.  For properties Fedify
+    does support, the functions return the current typed values encoded back
+    into JSON-LD.  The values are not verified, so validate them before use.
+    [[#1272], [#1356]]
+
  -  Added the `attributionDomains` property to `Application`, `Group`,
     `Organization`, `Person`, and `Service`, so applications can publish the
     domains an actor claims for Mastodon's `fediverse:creator` link credits
@@ -338,6 +358,17 @@ To be released.
      -  Fedify does not fill in a default license for objects without license
         metadata and never fetches a license URI.
 
+ -  Fixed accessors of objects decoded by `fromJsonLd()` returning wrong
+    values for embedded objects that have their own `@context`.  Such an
+    object was decoded again from its cached JSON-LD without the enclosing
+    document's context, so a type or property term that only the enclosing
+    context defined could yield an object of another class or drop
+    property values.  It could also pick embedded objects under a term that
+    the enclosing context mapped to another property.  The accessors now
+    apply the enclosing context and fall back to the object decoded with the
+    whole document when the cached JSON-LD cannot be matched with it.
+    [[#1272], [#1356]]
+
 [FEP-6757]: https://w3id.org/fep/6757
 [#1212]: https://github.com/fedify-dev/fedify/issues/1212
 [#1241]: https://github.com/fedify-dev/fedify/pull/1241
@@ -355,6 +386,11 @@ To be released.
     e.g., `zh-YUE` with `yue`.  `Intl.Locale` rejects extlang tags, so
     applications can normalize such tags before passing them to it.
     [[#1229], [#1231]]
+ -  Added the `VocabularyObject` interface, which every class generated by
+    `@fedify/vocab-tools` implements, and the `RawPropertyValue` type with its
+    `RawValueObject`, `RawNodeObject`, and `RawListObject` shapes for the
+    expanded JSON-LD values that `getRawPropertyValues()` returns.
+    [[#1272], [#1356]]
 
 [#1229]: https://github.com/fedify-dev/fedify/issues/1229
 [#1231]: https://github.com/fedify-dev/fedify/pull/1231
@@ -382,6 +418,18 @@ To be released.
     `https://w3id.org/identity/v1`.  Previously, such a property compacted to
     a prefixed name like `dc:license` without the extra context.
     [[#1212], [#1241]]
+ -  Fixed generated accessors decoding embedded objects that have their own
+    `@context` without the enclosing document's context, which could
+    return objects of another class, drop property values, or pick objects
+    under a term the enclosing context mapped to another property.
+    [[#1272], [#1356]]
+ -  Generated vocabulary modules now export `getRawPropertyValues()` and
+    `getRawPropertyValue()`, which read any property of a generated object
+    by its full IRI, and their root classes implement `VocabularyObject` from
+    `@fedify/vocab-runtime`.  Decoding retains the properties a class does not
+    know, so third-party vocabulary modules get the same access to
+    unsupported properties as `@fedify/vocab`.  The functions accept objects
+    from any generated module.  [[#1272], [#1356]]
  -  Made the generated `xsd:string` decoder skip JSON-LD values whose `@value`
     is not a string instead of placing them in string accessors.  Malformed
     remote values no longer leak numbers or booleans into properties such as

changes.d/lint/raw-property-iri-invalid.md

@@ -0,0 +1,11 @@
+---
+links:
+  '#1272': https://github.com/fedify-dev/fedify/issues/1272
+  '#1356': https://github.com/fedify-dev/fedify/pull/1356
+---
+ -  Added the `raw-property-iri-invalid` rule, which reports property IRIs
+    passed to `getRawPropertyValues()` and `getRawPropertyValue()` that throw
+    at runtime, such as terms and JSON-LD keywords, and compact IRIs such as
+    `as:content`, which are looked up literally.  With ESLint and Oxlint, the
+    `modules` option adds other vocabulary modules generated by
+    `@fedify/vocab-tools` to the default `@fedify/vocab`.  [[#1272], [#1356]]

changes.d/vocab-runtime/vocabulary-object.md

@@ -0,0 +1,10 @@
+---
+links:
+  '#1272': https://github.com/fedify-dev/fedify/issues/1272
+  '#1356': https://github.com/fedify-dev/fedify/pull/1356
+---
+ -  Added the `VocabularyObject` interface, which every class generated by
+    `@fedify/vocab-tools` implements, and the `RawPropertyValue` type with its
+    `RawValueObject`, `RawNodeObject`, and `RawListObject` shapes for the
+    expanded JSON-LD values that `getRawPropertyValues()` returns.
+    [[#1272], [#1356]]

changes.d/vocab-tools/embedded-object-context.md

@@ -0,0 +1,10 @@
+---
+links:
+  '#1272': https://github.com/fedify-dev/fedify/issues/1272
+  '#1356': https://github.com/fedify-dev/fedify/pull/1356
+---
+ -  Fixed generated accessors decoding embedded objects that have their own
+    `@context` without the enclosing document's context, which could
+    return objects of another class, drop property values, or pick objects
+    under a term the enclosing context mapped to another property.
+    [[#1272], [#1356]]

changes.d/vocab-tools/raw-property-values.md

@@ -0,0 +1,12 @@
+---
+links:
+  '#1272': https://github.com/fedify-dev/fedify/issues/1272
+  '#1356': https://github.com/fedify-dev/fedify/pull/1356
+---
+ -  Generated vocabulary modules now export `getRawPropertyValues()` and
+    `getRawPropertyValue()`, which read any property of a generated object
+    by its full IRI, and their root classes implement `VocabularyObject` from
+    `@fedify/vocab-runtime`.  Decoding retains the properties a class does not
+    know, so third-party vocabulary modules get the same access to
+    unsupported properties as `@fedify/vocab`.  The functions accept objects
+    from any generated module.  [[#1272], [#1356]]

changes.d/vocab/embedded-object-context.md

@@ -0,0 +1,15 @@
+---
+links:
+  '#1272': https://github.com/fedify-dev/fedify/issues/1272
+  '#1356': https://github.com/fedify-dev/fedify/pull/1356
+---
+ -  Fixed accessors of objects decoded by `fromJsonLd()` returning wrong
+    values for embedded objects that have their own `@context`.  Such an
+    object was decoded again from its cached JSON-LD without the enclosing
+    document's context, so a type or property term that only the enclosing
+    context defined could yield an object of another class or drop
+    property values.  It could also pick embedded objects under a term that
+    the enclosing context mapped to another property.  The accessors now
+    apply the enclosing context and fall back to the object decoded with the
+    whole document when the cached JSON-LD cannot be matched with it.
+    [[#1272], [#1356]]

changes.d/vocab/raw-property-values.md

@@ -0,0 +1,15 @@
+---
+links:
+  '#1272': https://github.com/fedify-dev/fedify/issues/1272
+  '#1356': https://github.com/fedify-dev/fedify/pull/1356
+---
+ -  Added `getRawPropertyValues()` and `getRawPropertyValue()` functions,
+    which read a property of a vocabulary object by its full IRI and return
+    its values in expanded JSON-LD.  They let applications read properties
+    that Fedify has no accessor for, such as an extension used by only a few
+    peers, without depending on the JSON-LD serialization cache: unknown
+    properties are now retained when an object is decoded, including embedded
+    objects, and survive `clone()` and `deepClone()`.  For properties Fedify
+    does support, the functions return the current typed values encoded back
+    into JSON-LD.  The values are not verified, so validate them before use.
+    [[#1272], [#1356]]

claude-plugin/skills/fedify/SKILL.md

@@ -277,6 +277,16 @@ overrides: `deepClone()` snapshots the existing indices of large sparse arrays.
 Entries added during copying are not visited, so their nested objects may
 remain shared.  Copying preserves array length and holes.
 
+To read a property that has no typed accessor, such as an application's
+extension, use `getRawPropertyValues(object, propertyIri)` or
+`getRawPropertyValue()` from `@fedify/vocab` (Fedify 2.5.0 and later) instead
+of digging through `toJsonLd()` output.  Pass the full property IRI, never a
+compact IRI like `as:content` or a term; prefixes are not expanded.  The
+results are untyped expanded JSON-LD values, unverified like any received
+data, so validate them before use.  For properties Fedify does support, the
+functions return the current typed values encoded back, not the received
+document.
+
 > [!WARNING]
 > `crossOrigin: "trust"` on vocabulary deserialization trusts embedded
 > objects without re-fetching.  Treat it as you would

docs/manual/lint.md

@@ -1782,6 +1782,84 @@ federation.setFollowersDispatcher(
 
 [*Filtering by server*]: ./collections.md#filtering-by-server
 
+### `raw-property-iri-invalid`
+
+Warns when statically known property IRIs passed to `getRawPropertyValues()`
+or `getRawPropertyValue()` are invalid or use a scheme other than
+`http:`/`https:`.  Named imports, aliases, and namespace imports are
+supported; shadowed local bindings are ignored.  See [*Reading unsupported
+properties*](./vocab.md#reading-unsupported-properties) for these functions.
+
+Raw-property helpers require full IRIs.  Empty strings, JSON-LD keywords,
+blank node identifiers, bare terms, relative references, and other invalid
+IRI strings throw `TypeError` at runtime.  IRIs with other schemes are
+accepted at runtime but both log a warning and trigger this rule: compact
+IRIs such as `as:content` are looked up literally, and prefixes are never
+expanded.  For well-known prefixes, the report includes the full IRI, which
+ESLint also offers as an editor suggestion.
+
+~~~~ typescript
+import { getRawPropertyValues } from "@fedify/vocab";
+
+// Reported: a bare term throws TypeError.
+await getRawPropertyValues(note, "content");
+
+// Reported: a compact IRI is looked up literally.
+await getRawPropertyValues(note, "as:content");
+
+// Use the full property IRI.
+await getRawPropertyValues(note, "https://www.w3.org/ns/activitystreams#content");
+~~~~
+
+The rule checks string literals, templates without expressions, `const`
+bindings to those, and global `new URL("…")` calls without a base argument.
+Dynamic values, `new URL(relative, base)`, and `URL` objects bound to
+a variable are ignored, since a `URL` object can be changed after it is
+constructed.  Inside a TypeScript namespace or enum, `const` bindings declared
+outside of it are ignored too, since another declaration of the same namespace
+or enum can shadow them.
+
+By default, only imports from `@fedify/vocab` are inspected, including
+`jsr:`/`npm:` and versioned specifiers.  The deprecated
+`@fedify/fedify/vocab` re-export is also inspected.  For other vocabulary
+modules generated with `@fedify/vocab-tools`, add their exact import
+specifiers to `modules`.
+The option adds to the defaults.  List each custom specifier form you use,
+such as both `@example/vocab` and `npm:@example/vocab`.
+
+~~~~ typescript
+// eslint.config.ts
+import { plugin } from "@fedify/lint";
+
+export default [{
+  plugins: { "@fedify/lint": plugin },
+  rules: {
+    "@fedify/lint/raw-property-iri-invalid": ["warn", {
+      modules: ["@example/vocab"],
+    }],
+  },
+}];
+~~~~
+
+Oxlint 1.31.0 or later is required to pass rule options:
+
+~~~~ jsonc
+// .oxlintrc.json
+{
+  "jsPlugins": ["@fedify/lint/oxlint"],
+  "rules": {
+    "@fedify/lint/raw-property-iri-invalid": ["warn", {
+      "modules": ["@example/vocab"]
+    }]
+  }
+}
+~~~~
+
+Deno Lint plugin rules cannot receive options, so this rule inspects only
+the default `@fedify/vocab` module specifiers there.  Like other Deno Lint
+plugin rules, its reports are errors.  ESLint's recommended configuration
+enables it as a warning; the strict configuration enables it as an error.
+
 ### `deno-kv-store-deprecated`
 
 Warns when `DenoKvStore` from the deprecated *@fedify/denokv* package is