{ "vercy": "1.0-draft", "publication": { "status": "research-draft", "adjudicationStatus": "unreviewed", "publishableCanonical": false, "generatedAt": "2026-09-12T10:12:02Z", "providers": [ "Codex" ], "breadth": "recalled by Codex without web access - no source was read", "missingProviders": [], "pass": 2, "cost": { "grok": { "seconds": 18.8, "error": "Reading additional input from stdin...\nOpenAI Codex v0.153.4\n--------\nworkdir: R:\\02_PROJECTS\\02_Meta_Models_Platforms\\Ver.cy\\current\\thing-registry-backlog\nmodel: gpt-6-astra\nprovider: openai\napproval: never\nsandbox: read-only\nreasoning effort: none\nreasoning summaries: none\nsession id: 01a09519-64e2-7c72-9a4f-2ded61f44991\n--------\nuser\nDescribe what is already known about one registered thing. Answer as JSON only, no prose around it.\n\nThing: HATEOAS\nSense to describe: (none recorded)\nDomain code: INF.KNW\nAlso known as: (none)\n\n\nContext for this batch of 1001 things:\n# Batch 043: 1001 registe", "usd": 0.0, "recall": true }, "codex": { "seconds": 58.0, "error": "Reading additional input from stdin...\nOpenAI Codex v0.153.4\n--------\nworkdir: R:\\02_PROJECTS\\02_Meta_Models_Platforms\\Ver.cy\\current\\thing-registry-backlog\nmodel: gpt-6-astra\nprovider: openai\napproval: never\nsandbox: read-only\nreasoning effort: none\nreasoning summaries: none\nsession id: 01a09519-64d9-7503-882e-2ea9d4882bb9\n--------\nuser\nYou are drafting a Vercy meta-model for one registered thing. Answer as JSON only, no prose around it.\n\nThing: HATEOAS\nRegistry id: vr.tr.hateoas\nPlane / domain: INF / INF.KNW\nRegistry definition: (none recorded)\nNames folded into this entry: (none)\n\n\nContext " } }, "enrichment": { "pass": 3, "engine": "claude", "producedAt": "2026-10-06T12:00:00Z", "ingestedAt": "2026-10-06T08:44:32+00:00", "fields": [ "agent_conduct", "ethics", "failure_modes_and_hazards", "owners", "standards_and_regulation" ] } }, "metaModel": { "id": "THING-Q5628978", "registryId": "vr.tr.hateoas", "name": "HATEOAS", "version": "0.1.0-research.1", "entryKind": "thing", "family": "Thing Registry", "domain": [ "INF.KNW" ], "status": "research-draft" }, "canonicalUrl": "https://ver.cy/models/thing/q5628978/", "model": { "registry_id": "vr.tr.hateoas", "name": "HATEOAS", "purpose": "Enable an agent to recognize, assess and use HATEOAS by recording how hypermedia controls guide application-state transitions at runtime.", "definition": "HATEOAS (Hypermedia as the Engine of Application State) is a constraint of REST in which clients select application-state transitions through hypermedia controls supplied in resource representations, using understood media types and link relations.", "scope_statement": "This model owns HATEOAS (Hypermedia as the Engine of Application State), registered as vr.tr.hateoas in INF / INF.KNW, as a REST constraint governing how clients discover and select application transitions through representations and understood hypermedia semantics.", "in_scope": [ "Discovery of application transitions through links, forms and other hypermedia controls", "Interpretation of controls through media types, link relations and documented semantics", "Distinction between client application state and server resource state", "Dependence on entry points, runtime controls and prior client knowledge", "Assessment of whether controls support usable and evolvable interactions" ], "out_of_scope": [ "The complete REST architectural style and its other constraints", "HTTP protocol semantics as a whole", "General API endpoint schemas and documentation systems", "Implementation of business workflows and resource persistence", "Authentication and authorization mechanisms themselves" ], "distinguishing_features": [ "A client discovers application-specific transition targets from received representations instead of constructing every target from a predefined endpoint map.", "Controls carry actionable meaning through understood relation and media-type semantics; a collection of unexplained URLs is insufficient evidence.", "Representations guide the next application interaction; merely returning JSON over HTTP does not establish HATEOAS.", "Clients still require an entry point and knowledge of relevant semantics; HATEOAS does not imply that arbitrary APIs explain themselves without prior knowledge.", "Controls can reflect the represented state and caller context, but an advertised action remains subject to server validation when attempted." ], "characteristics": [ { "name": "Transition discovery mechanism", "kind": "category", "unit_or_values": "representation controls | externally prescribed targets | mixed | unknown", "why_it_matters": "Identifies whether interaction depends on hypermedia or on a client-maintained endpoint map." }, { "name": "Hypermedia semantic contract", "kind": "relation", "unit_or_values": "Applicable media types, relation definitions, profiles and control specifications", "why_it_matters": "Connects each control to the rules an agent needs to interpret and execute it." }, { "name": "Prior client knowledge", "kind": "category", "unit_or_values": "Entry points, protocol semantics, media-type semantics, domain relations, URI construction rules and workflow assumptions", "why_it_matters": "Exposes the coupling that remains before runtime discovery begins." }, { "name": "Advertised transition coverage", "kind": "measurement", "unit_or_values": "Percentage of independently established applicable transitions exposed as interpretable controls within a declared workflow, state and caller context", "why_it_matters": "Measures coverage for a bounded evaluation without treating a single percentage as proof of REST conformance." }, { "name": "Control applicability", "kind": "state", "unit_or_values": "advertised | absent | stale | rejected on execution | unknown, relative to an observed representation", "why_it_matters": "Separates what the client was offered from what the server will currently accept." }, { "name": "Target relocation tolerance", "kind": "state", "unit_or_values": "demonstrated | failed | untested, for a declared client and transition set", "why_it_matters": "Tests whether the client follows supplied targets when application-specific URI layouts change." } ], "affordances": [ "Inspect representations and identify interpretable links, forms and action controls.", "Choose a control that advances the user's goal within the agent's authority.", "Construct an interaction using the target, method and input rules supplied or defined by the control's semantics.", "Trace workflows to detect hidden endpoint assumptions and missing transition controls.", "Test whether target relocation preserves client behavior.", "Refresh state and reassess available controls after stale or rejected transitions." ], "agent_conduct": { "may": [ "Design or consume APIs that follow hypermedia links supplied by the server.", "Explain the constraint and its trade-offs to developers." ], "must_not": [ "Follow links into actions it is not authorized to perform, such as deletes or payments.", "Expose links to resources users should not see in responses.", "Present an API as following the constraint when it does not." ], "requires_human": [ "Calling state-changing links that affect other people's data or money." ] }, "ethics": { "considerations": [ "Automated clients following links can take real actions on people's behalf." ], "affected_parties": [ "API users", "Developers", "Owners of the data" ] }, "owners": { "steward": "Nobody owns it; it is an architectural constraint.", "master_systems": [] }, "failure_modes_and_hazards": [ "Clients that follow links blindly can perform unintended actions.", "Leaked links can expose unauthorized operations." ], "standards_and_regulation": [ "RFC 8288, Web Linking, Internet Engineering Task Force." ], "what_it_is_for": [ "HATEOAS is used in REST systems where resource representations provide links or other controls for available application-state transitions.", "Clients interpret these controls through understood media types and link relations to discover relevant actions during interaction.", "It supports navigation and workflow changes without requiring clients to encode every resource address and transition in advance." ], "facets_not_applicable": { "recognition": "HATEOAS is an architectural constraint whose presence requires examining representations and interaction behavior rather than visual appearance." } }, "sources": [ { "id": "wikidata", "title": "Wikidata item Q5628978: HATEOAS", "url": "https://www.wikidata.org/wiki/Q5628978", "url_status": "live", "what_it_supports": "identity and sense of the item", "checked_by": "wikidata-api" }, { "id": "wikipedia-en", "title": "Wikipedia: HATEOAS", "url": "https://en.wikipedia.org/wiki/HATEOAS", "url_status": "live", "what_it_supports": "general description of the item", "checked_by": "wikidata-api sitelink" } ], "structure": { "bundles": [ { "id": "constraint-and-client-knowledge", "name": "Constraint and Client Knowledge", "description": "Establishes what HATEOAS requires and what the client must already understand.", "rationale": "Recognition depends on distinguishing runtime transition discovery from endpoint scripting and from the broader REST style.", "layers": [ { "id": "constraint-boundary", "name": "Constraint Boundary", "description": "Locates HATEOAS within the interaction architecture.", "findings": [ { "id": "hypermedia-drives-transitions", "name": "Hypermedia Drives Transitions", "description": "The defining concern is how representations guide application transitions, rather than the choice of serialization format.", "questions": [ { "text": "Which application transitions does the client discover from representations?", "kind": "definition", "id": "hypermedia-drives-transitions-q01" }, { "text": "Which claimed properties concern other REST constraints rather than HATEOAS?", "kind": "boundary", "id": "hypermedia-drives-transitions-q02" } ] } ] }, { "id": "bootstrap-and-assumptions", "name": "Bootstrap and Assumptions", "description": "Records the starting knowledge needed before controls can guide interaction.", "findings": [ { "id": "declared-prior-knowledge", "name": "Declared Prior Knowledge", "description": "Entry points and understood semantics enable discovery; hidden URI and workflow assumptions can undermine it.", "questions": [ { "text": "Which entry points, media types and domain relation meanings must the client know initially?", "kind": "definition", "id": "declared-prior-knowledge-q01" }, { "text": "Where does the client obtain application-specific URI construction rules or fixed transition sequences?", "kind": "provenance", "id": "declared-prior-knowledge-q02" } ] } ] } ] }, { "id": "controls-and-semantic-contract", "name": "Controls and Semantic Contract", "description": "Records how a representation expresses available interactions and their meaning.", "rationale": "An agent needs sufficient semantics to distinguish navigation from actions and to construct valid requests.", "layers": [ { "id": "control-recognition", "name": "Control Recognition", "description": "Identifies actionable representation elements under the applicable format.", "findings": [ { "id": "interpretable-control-elements", "name": "Interpretable Control Elements", "description": "A URI becomes a usable control through contextual semantics identifying its role and interaction rules.", "questions": [ { "text": "Which representation elements are defined as links, forms or other controls?", "kind": "definition", "id": "interpretable-control-elements-q01" }, { "text": "Which specification or documentation establishes those elements as controls rather than ordinary data?", "kind": "provenance", "id": "interpretable-control-elements-q02" } ] } ] }, { "id": "relation-and-request-semantics", "name": "Relation and Request Semantics", "description": "Connects a control's purpose to the rules for following or submitting it.", "findings": [ { "id": "executable-semantic-contract", "name": "Executable Semantic Contract", "description": "Control interpretation combines relation meaning with the applicable method, input and representation rules.", "questions": [ { "text": "Where are the control's relation meaning, request method and accepted inputs defined?", "kind": "provenance", "id": "executable-semantic-contract-q01" }, { "text": "How should the agent handle an unknown relation or unsupported control format?", "kind": "action", "id": "executable-semantic-contract-q02" }, { "text": "Which request details can be derived from the control and its semantics, and which require undocumented assumptions?", "kind": "boundary", "id": "executable-semantic-contract-q03" } ] } ] } ] }, { "id": "state-dependent-interaction", "name": "State-Dependent Interaction", "description": "Models how controls guide progress while represented conditions and server state change.", "rationale": "HATEOAS concerns application-state transitions, so a useful model must distinguish advertised possibilities from successful execution.", "layers": [ { "id": "application-and-resource-state", "name": "Application and Resource State", "description": "Separates the client's interaction progress from the state of server resources.", "findings": [ { "id": "contextual-transition-options", "name": "Contextual Transition Options", "description": "A received representation provides transition options in an observed context without guaranteeing that every option remains executable.", "questions": [ { "text": "What client application state and represented resource state frame the available controls?", "kind": "definition", "id": "contextual-transition-options-q01" }, { "text": "How do controls vary across resource states and caller contexts?", "kind": "measurement", "id": "contextual-transition-options-q02" }, { "text": "Does an absent control mean unavailable, unauthorized, omitted or simply unknown under this contract?", "kind": "boundary", "id": "contextual-transition-options-q03" } ] } ] }, { "id": "execution-and-recovery", "name": "Execution and Recovery", "description": "Determines how an agent acts on controls and responds to changed conditions.", "findings": [ { "id": "validated-transition-execution", "name": "Validated Transition Execution", "description": "The server evaluates an attempted transition against current conditions; clients need recovery behavior when advertised controls become stale or requests fail.", "questions": [ { "text": "What user authority and control semantics justify executing the selected transition?", "kind": "action", "id": "validated-transition-execution-q01" }, { "text": "After rejection or a stale-state response, which representation or control allows the agent to reassess its next step?", "kind": "action", "id": "validated-transition-execution-q02" } ] } ] } ] }, { "id": "discovery-and-evolution-evidence", "name": "Discovery and Evolution Evidence", "description": "Evaluates whether concrete clients use hypermedia effectively across workflows and changes.", "rationale": "The presence of links alone cannot demonstrate useful discovery or reduced dependence on endpoint layouts.", "layers": [ { "id": "workflow-discoverability", "name": "Workflow Discoverability", "description": "Examines whether declared goals can be pursued through understood runtime controls.", "findings": [ { "id": "bounded-transition-coverage", "name": "Bounded Transition Coverage", "description": "Coverage is assessed against a stated workflow and independently identified applicable transitions, including the states and caller contexts examined.", "questions": [ { "text": "For the selected workflow, which applicable transitions are exposed through interpretable controls?", "kind": "measurement", "id": "bounded-transition-coverage-q01" }, { "text": "At which steps must the client consult an external endpoint recipe or invent a target?", "kind": "boundary", "id": "bounded-transition-coverage-q02" } ] } ] }, { "id": "change-tolerance", "name": "Change Tolerance", "description": "Tests which server changes a client can accommodate while the relevant semantic contracts remain stable.", "findings": [ { "id": "observed-decoupling", "name": "Observed Decoupling", "description": "Following supplied targets can tolerate URI changes, while incompatible changes to relation meanings or control formats may still require client changes.", "questions": [ { "text": "Does the client complete the workflow when supplied transition targets change but their semantics remain stable?", "kind": "measurement", "id": "observed-decoupling-q01" }, { "text": "Which changes to media types, relation meanings or required inputs break the client's interpretation?", "kind": "boundary", "id": "observed-decoupling-q02" }, { "text": "What recorded interaction traces support the claimed degree of change tolerance?", "kind": "provenance", "id": "observed-decoupling-q03" } ] } ] } ] }, { "id": "evidence-and-external-alignment", "name": "Evidence and external alignment", "description": "What the world already says about this thing, gathered so the model can be checked against it.", "rationale": "A model that cannot be lined up against existing standards, identifiers and practice cannot be adopted by anyone who already uses them.", "layers": [ { "id": "reported-evidence", "name": "Reported evidence", "description": "Findings from the breadth pass, kept separate from the structural claims.", "findings": [ { "id": "evidence-confidence-notes", "name": "Check these first", "description": "Recalled without web access and unsourced; every item is a lead to verify.", "evidence": [ "HATEOAS is an architectural constraint, not a discipline or field of knowledge.", "Its conceptual source is Roy Fielding's REST architectural work; the standards named here provide related mechanisms rather than a standalone HATEOAS certification scheme.", "This is recall only; no sources were consulted, and judgments about particular implementations require examining their controls and client behavior." ], "questions": [ { "id": "evidence-confidence-notes-q01", "text": "Which of these check these first hold for the sense of HATEOAS this model covers, and on what evidence?", "kind": "provenance" } ] }, { "id": "evidence-standards-and-regulation", "name": "Standards and regulation", "description": "Recalled without web access and unsourced; every item is a lead to verify.", "evidence": [ "IETF RFC 8288, Web Linking, defines a framework for typed links and the HTTP Link header; it supports hypermedia interaction but does not itself establish HATEOAS compliance.", "IANA maintains the Link Relation Types registry, which provides registered relation names for interpreting links." ], "questions": [ { "id": "evidence-standards-and-regulation-q01", "text": "Which of these standards and regulation hold for the sense of HATEOAS this model covers, and on what evidence?", "kind": "provenance" } ] }, { "id": "evidence-real-world-use", "name": "Real-world use", "description": "Recalled without web access and unsourced; every item is a lead to verify.", "evidence": [ "Web navigation through hyperlinks and forms.", "Hypermedia APIs that expose available actions and related resources in responses.", "Workflow APIs that expose different permitted transitions as a resource moves through its lifecycle.", "Reducing client dependence on hard-coded endpoint paths by supplying navigation controls at runtime." ], "questions": [ { "id": "evidence-real-world-use-q01", "text": "Which of these real-world use hold for the sense of HATEOAS this model covers, and on what evidence?", "kind": "provenance" } ] }, { "id": "evidence-failure-modes-and-hazards", "name": "Failure modes and hazards", "description": "Recalled without web access and unsourced; every item is a lead to verify.", "evidence": [ "Clients hard-code workflow transitions and endpoint paths, bypassing supplied hypermedia controls.", "Responses contain links without sufficiently defined relation or action semantics for clients to interpret them.", "Servers expose stale or unusable controls that no longer match resource state or client permissions.", "Implementations mistake the presence of hyperlinks for satisfaction of all REST constraints.", "Servers treat omission of an action link as authorization enforcement instead of checking permissions when the action is requested." ], "questions": [ { "id": "evidence-failure-modes-and-hazards-q01", "text": "Which of these failure modes and hazards hold for the sense of HATEOAS this model covers, and on what evidence?", "kind": "provenance" } ] }, { "id": "evidence-neighbours", "name": "Neighbouring kinds and how to tell them apart", "description": "Recalled without web access and unsourced; every item is a lead to verify.", "evidence": [ { "name": "REST", "difference": "REST is an architectural style with multiple constraints; HATEOAS is part of its uniform-interface constraint." }, { "name": "Hypermedia", "difference": "Hypermedia supplies navigable links and interaction controls; HATEOAS requires those controls to drive application-state transitions." }, { "name": "HTTP", "difference": "HTTP specifies communication semantics; using HTTP does not establish that an application follows HATEOAS." }, { "name": "OpenAPI", "difference": "OpenAPI describes HTTP API interfaces; an interface description alone does not make runtime interactions driven by hypermedia." }, { "name": "Resource state", "difference": "Resource state concerns the condition or information represented by a resource; the application state in HATEOAS concerns the client's progress through interactions." } ], "questions": [ { "id": "evidence-neighbours-q01", "text": "Which of these neighbouring kinds and how to tell them apart hold for the sense of HATEOAS this model covers, and on what evidence?", "kind": "provenance" } ] } ] } ] } ] }, "openQuestions": [ "Which authoritative architectural passages and subsequent clarifications should anchor this registry entry's exact definition of HATEOAS?", "Which hypermedia formats and relation vocabularies should supply representative examples without making the model format-specific?", "What evaluation convention should distinguish partial hypermedia adoption from adequate HATEOAS support for a declared workflow?", "How should transition coverage be established when the complete set of applicable actions is not independently observable?", "Does the existing Vercy catalogue already contain a REST or hypermedia model that owns this concept and should be linked instead of duplicated?" ], "statistics": { "bundles": 5, "layers": 9, "findings": 13, "questions": 24 } }