About the specifications
Note
Project status: pre-alpha. Core contracts have source implementations and conformance tests; approval, evidence, and local API implementations are partial and still need milestone validation. The first experimental CLI and Unix-daemon release is available; contracts remain subject to change before 1.0. Tests check implemented wire values against the schemas.
The specifications define the contracts that make Shiin interchangeable: the action request, the decision, the evaluation pipeline, and the approval protocol, along with JSON Schemas and test vectors that other tools can implement.
Each page distinguishes implemented behavior from remaining design work. The roadmap lists the milestone that delivers each specification’s implementation.
Status and lifecycle
| Status | Meaning |
|---|---|
draft | The specification is under active revision. Field names, IDs, and schemas may change. |
proposed | The specification has stabilized enough to send to implementers for review. |
accepted | The content is settled and may be implemented against. Before 1.0 a correction may still raise the draft minor version, recorded in the revision history; after 1.0 a change requires a superseding version. |
superseded | A newer version replaces this one. Links to the replacement. |
The status field in each page’s metadata reflects where the specification is in this lifecycle, not whether code exists.
Versioning
Each specification states its version near the top, in the form shiin.<name>/v<major>-draft.<minor>:
- The major version is part of the schema
$idURN (for example,urn:shiin:schema:action-request:v1). - A draft minor number (
.1,.2, …) increments for any change that is not a new major version. - A new major version is issued when a change is not backward compatible.
- The version string in the specification text, the
$idin the schema, and the schema file name must all agree.
Requirement IDs
Every normative requirement in a specification starts with a bold, bracketed requirement ID, for example **[AR-001]**.
- IDs are unique across all documentation and are defined only in their owning
kind=specpage. - The prefix indicates which specification owns the requirement:
| Prefix | Specification |
|---|---|
AT | Action types |
AR | Action request |
DEC | Decision |
EVAL | Evaluation |
ID | Identity |
POL | Policy model |
SYN | Policy syntax |
INT | Intent binding |
RISK | Risk signals |
APR | Approval protocol |
AUD | Audit events |
RCPT | Receipts |
ADP | Adapter contract |
API | Local API |
SEC | Security model |
Schemas and test vectors
- JSON Schemas live in
schemas/and are named<name>.v<major>.schema.json. - Shared definitions live in
common.v1.schema.jsonand are referenced by$id. - Test vectors live in
test-vectors/and are validated againsttest-vector.v1.schema.json.
Specification list
| Specification | Milestone | Schema |
|---|---|---|
| Action types | v0.1 | — |
| Action request | v0.1 | schema |
| Decision | v0.1 | schema |
| Evaluation | v0.1 | schema |
| Identity | v0.1 | — |
| Policy model | v0.1 | — |
| Policy syntax | v0.1 | schema |
| Intent binding | v0.2 | schema |
| Risk signals | v0.1 | schema |
| Approval protocol | v0.3 | schema |
| Audit events | v0.1 | schema |
| Receipts | v0.4 | receipt, checkpoint, encrypted replay |
| Adapter contract | v0.1 | — |
| Local API | v0.5 | schema |
| Test vectors | m0 | schema |
Reading the specifications
- Start with How Shiin works for the end-to-end flow.
- Read the action request and decision for the core messages.
- Read evaluation for how decisions are combined.
- Read the adapter contract for integration.
- Consult the test vectors for concrete examples.