Advisory Vocabulary v1.0 Draft (v1.0-draft.0.2)

Overview

Namespace URI:

https://ns.cascadeprotocol.org/advisory/v1#

Preferred Prefix:

advisory:

Version:

1.0-draft.0.2 (2026-08-20)

Status:

Draft

Imports:

cascade: (Core v1)

Underlying spec:

W3C Linked Data Patch Format (Recommendation, 2015)

Schema files:

advisory.ttl (OWL ontology) · advisory.shapes.ttl (SHACL shapes)

The Advisory Vocabulary defines the Cascade Advisory Patch (CAP) profile: a strict subset of W3C LDPatch designed for clinical knowledge updates that are author-readable, statically auditable, and bounded in execution. Forward-compatible with full LDPatch — every CAP file is a valid LDPatch file.

What this vocabulary covers

• The CAP envelope. advisory:CascadeAdvisoryPatch with required metadata (humanSummary, advisoryClass, issuer, issuedAt) plus optional supersedes, applicableUntil, cadence, profileVersion, evidenceUrl, appliesToActiveOnly.
• Six AdvisoryClass categories (closed taxonomy): SafetyCritical (every-app-open), VariantReclassification (monthly), DrugInteraction (monthly), LabReferenceRangeUpdate (quarterly), SurveillanceGuidelineUpdate (quarterly to annual), CarrierFrequencyUpdate (annual).
• Six Cadence individuals: EveryAppOpen, Daily, Weekly, Monthly, Quarterly, Annually.
• Detached JWS Ed25519 signing envelope (RFC 7515 compact serialization) per D-Q4. Properties: signature, signatureIssuer, signatureIssuedAt, signatureExpiresAt, signatureContentType (fixed to application/x-cascade-advisory-patch). W3C VC 2.0 wrapping is deferred to a later profile version.
• Per-pod TrustedIssuer per D-Q3. advisory:TrustedIssuer with TrustSourceEnum provenance (RecommendedStarterList, UserAdded, ImportedFromRegistry, VerifiedViaDID). The protocol does NOT define a centralized issuer registry — each pod carries its own trust graph at <pod>/trust/issuers.ttl.
• Auto-apply policy. advisory:AutoApplyPolicy with per-(issuer, advisoryClass) AutoApplyScope tuples; effective-from / effective-until windows; forward-compat requiresQuorum flag (unused in v0.1).

CAP profile constraints

A document conforms to CAP if all six constraints below hold. Full prose lives in cascadeprotocol.org/drafts/advisory-v1/PROFILE.md.

• C1: Operations restricted to Add and Bind. No Delete, Cut, or UpdateList. Supersession is expressed additively via prov:wasRevisionOf — every application is monotonic and roll-forward auditable.
• C2: At most one Bind per advisory, restricted to single-identifier match. The path expression must be ?var <predicate> <literal> where the predicate is on a published whitelist (genomics:caId, genomics:vrsId, genomics:clinvarVariationId, clinical:loincCode, clinical:rxNormCode, clinical:icd10Code, clinical:snomedCode, genomics:hgncId). Applier cost is O(index lookup), not O(graph traversal).
• C3: No prefix manipulation. Whitelisted prefixes only.
• C4: No IRI computation. All IRIs are either literal strings from the patch or the bound ?var. No CONCAT, template substitution, or string-to-IRI conversion.
• C5: Bounded insert size. At most 64 triples per match.
• C6: Required envelope metadata (humanSummary, advisoryClass, issuer, issuedAt) declared before any operation.

Key classes

The cascade:AdvisoryApplicationActivity class — which records advisory-application events as a prov:Activity — is declared in core v3.1 and is referenced here, not redeclared.

Application pipeline (informative)

A CAP applier validates a candidate patch in this order:

1. Parse as LDPatch. Any LDPatch syntax error → reject.
2. Profile envelope check. Required advisory: metadata present and well-formed → continue, else reject.
3. Constraint check. C1–C5 enforced statically → continue, else reject.
4. Signature verification. Detached-JWS signature valid against trusted-issuer keys → continue, else queue for explicit user trust review.
5. Selector evaluation. Bind query against pod — zero matches: log inapplicable; one match: proceed; N matches: each treated as separate application.
6. Application. Inserts performed; cascade:AdvisoryApplicationActivity recorded with prov:used linking to patch + matched node.

Validation (SHACL)

advisory.shapes.ttl defines four sh:NodeShape declarations enforcing:

• Required envelope fields (humanSummary, advisoryClass, issuer, issuedAt).
• Closed enumerations on advisoryClass, cadence, trustSource.
• appliesTo cardinality on AutoApplyPolicy.
• AutoApplyScope structure (issuer + advisoryClass tuple).

Issuer-trust allowlist enforcement is OUT of SHACL scope per D-Q3 — that's a runtime concern, lives in <pod>/trust/issuers.ttl.

Worked examples

• example-brca2-reclassification.ldpatch — a VUS reclassified to Likely Pathogenic.
• example-cpic-cyp2c19-warfarin.ldpatch — CPIC PGx dosing guidance update tied to a CYP2C19 star allele.

Both files live at cascadeprotocol.org/drafts/advisory-v1/ and are valid LDPatch conforming to the CAP profile.

References

• Per-vocab changelog: spec/ontologies/advisory/CHANGELOG.md
• CAP profile prose: cascadeprotocol.org/drafts/advisory-v1/PROFILE.md.
• Implementation plan: 05-04-26 Genomics & Advisory IMPLEMENTATION-PLAN.md.
• Schema reference: cascade-protocol-schemas.md (Advisory section).
• W3C LDPatch: https://www.w3.org/TR/ldpatch/

Provide Feedback

This vocabulary is in draft status. We welcome feedback on the CAP profile constraints, the issuer-trust model, and any gaps in the AdvisoryClass taxonomy. Submit Feedback