119 lines
5.2 KiB
Markdown
119 lines
5.2 KiB
Markdown
# Semantic Documentation Subjects
|
|
|
|
## Purpose And Ownership
|
|
|
|
The semantic-documentation subject contract lets an optional module expose the
|
|
configured artifacts that administrators may document: for example a form, a
|
|
form field, a workflow, or a workflow state. It is a discovery and resolution
|
|
contract, not a second configuration API.
|
|
|
|
The module that owns an artifact also owns its subject provider, authorization,
|
|
identity, revision, route, and lifecycle semantics. Docs may discover those
|
|
providers through Core and attach authored documentation to their stable
|
|
references. Docs must not import the feature module, read its tables, or copy
|
|
configuration content into a generic index.
|
|
|
|
This contract is additive to manifest `DocumentationTopic` contributions and
|
|
configured-state `documentation_providers`. Every providing module must retain
|
|
static user and administrator documentation baselines. The baselines explain
|
|
the feature even when the provider is disabled, unavailable, or has no
|
|
configured subjects.
|
|
|
|
## Identity And Versioning
|
|
|
|
`SemanticDocumentationSubjectReference` identifies a subject with:
|
|
|
|
- owning module and tenant;
|
|
- a module-defined subject kind and stable identifier;
|
|
- an optional typed nested anchor, such as `field/registration-number`;
|
|
- the revision and canonical fingerprint observed when documentation was
|
|
authored or reviewed.
|
|
|
|
The `stable_key` derives only from identity. A rename or configuration revision
|
|
therefore does not detach existing documentation. A nested anchor has its own
|
|
identity so a field can be documented independently from its form.
|
|
|
|
Providers must resolve an old reference as one of:
|
|
|
|
- `available`: the observed revision/fingerprint is still current;
|
|
- `changed`: the same stable subject has changed and may need review;
|
|
- `superseded`: another stable reference replaced it;
|
|
- `missing`: the subject was removed or is no longer resolvable;
|
|
- `temporarily_unavailable`: the provider cannot currently determine state.
|
|
|
|
Absence is not authorization. A provider returns `None` when the principal may
|
|
not learn whether a subject exists. Core also rejects cross-tenant list and
|
|
resolution requests before calling a provider.
|
|
|
|
## Safe Projection
|
|
|
|
Descriptors contain only bounded, explicit presentation fields: localized
|
|
labels and descriptions, breadcrumbs, a local route, audience,
|
|
classification, and required scopes. They must not contain credentials,
|
|
personal data, arbitrary provider metadata, configuration payloads, or the
|
|
authored documentation itself. Routes are application-local and are still
|
|
subject to normal route authorization.
|
|
|
|
The fingerprint is a review signal, not a concurrency token or a content hash
|
|
that callers may use to reconstruct configuration. Providers should calculate
|
|
it from the smallest canonical JSON projection whose semantic changes require
|
|
documentation review. Volatile timestamps and secrets must be excluded.
|
|
|
|
## Provider Registration
|
|
|
|
A provider is registered under its exact module-scoped capability name:
|
|
|
|
```python
|
|
from govoplan_core.core.modules import CapabilityDocumentation
|
|
from govoplan_core.core.semantic_documentation import (
|
|
SEMANTIC_DOCUMENTATION_SUBJECT_CONTRACT_VERSION,
|
|
semantic_documentation_subject_capability,
|
|
)
|
|
|
|
capability = semantic_documentation_subject_capability("forms")
|
|
|
|
manifest = ModuleManifest(
|
|
id="forms",
|
|
# ...
|
|
capability_factories={capability: build_semantic_subject_provider},
|
|
capability_documentation={
|
|
capability: CapabilityDocumentation(
|
|
label="Form semantic subjects",
|
|
summary="Lists authorized configured forms and fields for Docs.",
|
|
contract_version=SEMANTIC_DOCUMENTATION_SUBJECT_CONTRACT_VERSION,
|
|
documentation_types=("admin", "user"),
|
|
)
|
|
},
|
|
documentation=(admin_baseline, user_baseline),
|
|
)
|
|
```
|
|
|
|
The capability is `documentation.semantic_subjects.<module_id>`. Registry
|
|
validation rejects a mismatched owner, missing capability documentation, a
|
|
wrong contract version, or missing static baselines.
|
|
|
|
`list_semantic_documentation_subjects` performs authorized, paginated discovery
|
|
across installed providers. `resolve_semantic_documentation_subject` targets
|
|
one owner without loading another feature module. Providers must apply the
|
|
current tenant and principal on every call and must not infer visibility from a
|
|
previous list result.
|
|
|
|
## Lifecycle And Integration Rules
|
|
|
|
- Keep subject and anchor identifiers stable across display-name and route
|
|
changes.
|
|
- Return `superseded` only with the replacement reference; do not silently
|
|
rewrite stored references.
|
|
- Return a reason code for missing or temporarily unavailable subjects without
|
|
exposing sensitive detail.
|
|
- Reauthorize both discovery and resolution. Stored documentation references
|
|
confer no access to a live artifact.
|
|
- Treat a changed fingerprint as a request for editorial review. It does not
|
|
automatically invalidate or publish authored documentation.
|
|
- Removing a feature module leaves references resolvable as provider
|
|
unavailable. Docs can preserve history without importing the module.
|
|
|
|
Forms, Workflow, and later modules should implement their subject providers in
|
|
their own repositories. Docs owns the authored semantic-documentation records,
|
|
review workflow, and projection UI.
|