{"$schema":"https://embeddedsemantics.com/schemas/embedded-semantics-interaction-guide-v1.schema.json","inputErrors":[{"code":"missing_expression","correction":"Send a JSON object with a non-empty expression string.","meaning":"The JSON body omitted the required expression field."},{"code":"invalid_expression_type","correction":"Send expression as a JSON string.","meaning":"The expression value was not a string."},{"code":"blank_expression","correction":"Send the exact non-blank expression that requires identity resolution.","meaning":"The expression contained no text after trimming."},{"code":"invalid_unicode_expression","correction":"Send valid UTF-8 JSON text.","meaning":"The expression was not valid Unicode scalar text."},{"code":"expression_too_long","correction":"Send one bounded expression of 1000 characters or fewer, not the whole conversation.","meaning":"The expression exceeded the 1000-character request limit."},{"code":"invalid_language_tag","correction":"Use a valid tag such as en, es, ja, or omit language when unknown.","meaning":"The optional language value was not a valid BCP 47 tag."}],"interpretationOrder":[{"check":"error is not null","meaning":"The request was invalid or the service could not provide a semantic result.","nextAction":"Repair or report only the stated error. Assign no ConceptCode.","step":1},{"check":"data.status == \"resolved\" and data.concept.code is a non-empty string","meaning":"The governed registry returned an authoritative published identity.","nextAction":"Use the exact returned code and preserve registryVersion.","step":2},{"check":"data.status == \"abstained\"","meaning":"The resolver intentionally assigned no ConceptCode.","nextAction":"Preserve data.reason and follow the matching abstention guidance. Never guess.","step":3},{"check":"anything else","meaning":"The response does not satisfy the published contract.","nextAction":"Fail closed, assign no ConceptCode, and report a contract error.","step":4}],"invariants":["HTTP success is transport success only; inspect data.status.","Every abstained result means no ConceptCode assignment.","Candidates, scores, confidence, margin, embeddings, and model output are not semantic authority.","A ConceptCode is semantic identity evidence and never authorization to execute an action.","Desktop applications and local models are API clients; calling the API requires no hosted execution provider."],"outcomes":{"ambiguous_expression":{"agentNextAction":"Assign no ConceptCode until new governed evidence or human clarification resolves the ambiguity.","humanExplanation":"The expression needs more context before one ConceptCode can be selected safely.","humanNextAction":"Ask a clarifying question that distinguishes the possible meanings, then submit the clarified expression.","match":"data.status == \"abstained\" and data.reason == \"ambiguous_expression\"","meaning":"More than one governed exact identity remains possible.","prohibited":"Do not choose a candidate silently or use model confidence as authority."},"input_or_service_error":{"agentNextAction":"Assign no ConceptCode and expose the exact error code/message to the caller.","humanExplanation":"The request needs correction or the service response could not be trusted.","humanNextAction":"Correct the stated input problem or report the service failure, then retry only when appropriate.","match":"error is not null or the response violates the published envelope","meaning":"No semantic result was produced.","prohibited":"Do not fill the gap with an inferred semantic result."},"other_abstention":{"agentNextAction":"Assign no ConceptCode regardless of candidates, confidence, margin, or model metadata.","humanExplanation":"The service did not assign a ConceptCode and reported the reason in data.reason.","humanNextAction":"Preserve the reason and follow any deployment or evidence guidance without inventing identity.","match":"data.status == \"abstained\" with any other data.reason","meaning":"The resolver intentionally declined to assign semantic identity.","prohibited":"Do not convert an abstention into a best-effort resolution."},"resolved":{"agentNextAction":"Preserve code and registryVersion exactly; apply a separate authorization policy before any action.","humanExplanation":"A governed identity was found. The ConceptCode below is the registry-backed result, not a guess.","humanNextAction":"Review the Concept name and definition, then use the code only for the intended semantic reference.","match":"data.status == \"resolved\" and data.concept.code is a non-empty string","meaning":"Reviewed registry evidence identified one published Concept.","prohibited":"Do not rewrite, shorten, translate, alias, or reconstruct the returned ConceptCode."},"unknown_expression":{"agentNextAction":"Assign no ConceptCode and preserve unknown_expression.","humanExplanation":"No reviewed registry identity was found. This is a deliberate unknown result, not a system guess.","humanNextAction":"Recheck the wording or preserve the expression as unresolved; do not substitute a likely code.","match":"data.status == \"abstained\" and data.reason == \"unknown_expression\"","meaning":"No governed reviewed exact identity is available for this expression.","prohibited":"Do not infer from labels, candidates, similarity, embeddings, or local-model intuition."}},"purpose":"Explain what to send, how to interpret every resolver outcome, what a human should be told, and which next actions are safe without changing semantic authority.","readiness":{"note":"Readiness describes the deployed corpus. It never changes the decision rule: only an explicit resolved response with a non-empty ConceptCode assigns identity.","positiveResolutionPossible":false,"productionResolver":"reviewed_exact_registry_first","publicBundleComplete":false,"publishedConcepts":0,"reviewedExactExpressions":0},"request":{"contentType":"application/json","example":{"expression":"stable concept identity","language":"en"},"method":"POST","minimumDataRule":"Send only the exact expression that needs a governed identity and an optional known BCP 47 language tag. Do not send credentials, hidden prompts, unrelated conversation, or private context.","optionalFields":["language"],"readOnly":true,"requiredFields":["expression"],"url":"https://embeddedsemantics.com/api/v1/resolve"},"schema":"embedded-semantics.interaction-guide.v1","service":{"agentGuide":"https://embeddedsemantics.com/agents","canonicalOrigin":"https://embeddedsemantics.com","capabilities":"https://embeddedsemantics.com/api/v1/capabilities","humanGuide":"https://embeddedsemantics.com/try","instructions":"https://embeddedsemantics.com/agent-instructions.txt","name":"Embedded Semantics","resolve":"https://embeddedsemantics.com/api/v1/resolve","status":"https://embeddedsemantics.com/api/v1/status"},"version":"1.0.0"}