Service Contract Authoring Guide

2026-08-12

Purpose

This document defines the requirements for authoring Elonn Service contracts.

It establishes the structure, content, conventions, and publication requirements for every Service contract published by the Elonn platform.

This guide defines the Service contract model and the rules governing how Service contracts are authored, published, and maintained.

This guide applies to all published Service contracts regardless of whether they are developed by Elonn or by third parties.

This guide defines Service contracts only. It does not define platform architecture, Service implementation, operational policy, or organizational processes except where they directly affect the published Service contract.

Service Contracts

A Service contract is the authoritative published definition of an Elonn Service.

Every Service publishes exactly one Service contract.

A Service contract defines the Service and every platform endpoint exposed by that Service. It defines the requests accepted by each endpoint, the responses returned, the data structures used, authentication and authorization requirements, side effects, privacy considerations, error conditions, and all other information required to communicate with the Service.

A Service contract is the single source of truth for the Service's platform interface. Information describing the platform interface of a Service shall not be defined outside the Service contract.

Every client consumes the same published Service contract. Service contracts are not specialized for first-party Services, runtime components, deterministic software, reasoning models, development tools, or third-party applications.

Every Service contract is published in two representations.

The canonical JSON representation is the normative definition of the Service contract and is intended for machine consumption.

The Markdown representation describes the same Service contract for human readers. It shall not conflict with, redefine, or extend the canonical JSON contract.

Together, the JSON and Markdown representations constitute the published Service contract.

Contract Principles

The following principles govern the design, publication, and evolution of every Elonn Service contract.

One Contract

Every Service publishes exactly one Service contract.

A Service contract defines the complete platform interface of the Service.

Canonical

Every Service contract has one canonical representation.

The canonical representation is the published JSON contract.

Human Representation

Every Service contract is also published as a Markdown document.

The Markdown representation describes the same Service contract for human readers.

The Markdown representation shall not conflict with the canonical JSON contract.

Single Source of Truth

The Service contract is the authoritative definition of a Service's platform interface.

Platform interface information shall not be defined outside the published Service contract.

Universal Consumption

Every client consumes the same published Service contract.

Service contracts shall not vary based on the type of consumer.

Platform Interface

Service contracts describe the platform interface of a Service.

Service implementation details shall not be included unless they directly affect the platform interface.

Discoverability

Every Service contract shall be published at a predictable location.

The Service Registry enables Service discovery by indexing Service Publications that locate published Service contracts. It does not redefine, duplicate, or extend Service contract contents.

Consistency

Equivalent concepts shall be represented consistently throughout the Elonn platform.

Canonical platform structures shall not be redefined by individual Services.

Stability

Service contracts should evolve without unnecessarily disrupting existing consumers.

Changes to published contracts should preserve compatibility whenever practical.

Efficiency

Information shall be defined once within the canonical Service contract.

Contracts shall avoid duplication, ambiguity, and unnecessary complexity.

Contract Structure

Every Service contract shall follow a consistent structure.

A consistent contract structure improves discoverability, simplifies tooling, reduces ambiguity, and allows every published Service contract to be understood in a predictable manner.

The canonical JSON representation defines the structure of the Service contract. The Markdown representation presents the same contract for human readers.

Service Definition

Every Service contract shall define the Service.

The Service definition identifies the Service and provides the information common to every endpoint exposed by the Service.

Endpoint Definitions

Every platform endpoint exposed by a Service shall be defined by the Service contract.

Each endpoint definition shall describe the endpoint, its purpose, request and response structures, authentication and authorization requirements, side effects, privacy considerations, error conditions, and any other information required to invoke the endpoint correctly.

Data Structures

Every data structure used by a Service contract shall be defined or referenced by the contract.

Canonical platform structures shall be referenced.

Service-specific structures shall be defined by the Service contract.

A data structure shall be defined once and referenced wherever it is used.

Authentication

The Service contract shall define the authentication requirements for communicating with the Service.

Authentication requirements common to all endpoints should be defined once at the Service level. Endpoint-specific requirements shall be defined by the endpoint.

Authorization

The Service contract shall define the authorization requirements for every endpoint.

Authorization requirements shall clearly identify any permissions, capabilities, or conditions required to successfully invoke an endpoint.

Errors

The Service contract shall define the errors that may be returned by the Service.

Errors common to multiple endpoints should be defined once and referenced by endpoint definitions where appropriate.

Publication

Every Service contract shall identify its published representations and any additional published artifacts required by the platform, including the Service changelog.

The locations of published artifacts shall conform to the platform publication requirements.

Contract Representations

Every Service contract shall be published in two representations:

A canonical JSON representation.
A human-readable Markdown representation.

Both representations describe the same Service contract.

The canonical JSON representation is normative.

The Markdown representation documents the canonical Service contract for human readers.

The canonical JSON and Markdown representations serve different purposes and are not required to share the same organization.

The canonical JSON representation shall conform to the canonical Service contract schema.

Canonical JSON Contract

The canonical JSON representation is the authoritative definition of a Service contract.

The canonical JSON representation is normative.

Every published Service contract shall include a canonical JSON representation.

The canonical JSON representation is intended for machine consumption.

The canonical JSON representation shall conform to the canonical Service contract schema.

Canonical Service Contract Shape

Every canonical Service contract JSON document shall use this top-level shape:

{
  "service": {
    "id": "maps.elonn",
    "name": "Maps",
    "domain": "spatial",
    "purpose": "Provides spatial information and geographic capabilities."
  },
  "contract": {
    "revision": 1,
    "published": "2026-08-18T00:00:00Z"
  },
  "labels": {
    "field.query_text": "Search",
    "field.result_limit": "How many results"
  },
  "invocation": {
    "base_url": "https://maps.elonn.com"
  },
  "authentication": {
    "required": true,
    "scheme": "elonn-service"
  },
  "endpoints": [
    {
      "id": "maps.search",
      "method": "POST",
      "path": "/maps/call",
      "purpose": "Find places or spatial information.",
      "request": {
        "structure": "Call"
      },
      "response": {
        "structure": "Dataset"
      },
      "authorization": [],
      "side_effects": false,
      "privacy": [],
      "errors": [],
      "operations": [
        {
          "id": "maps.search",
          "purpose": "Find places or spatial information.",
          "arguments": {
            "text": {"type": "string", "required": true, "source": "model", "label_ref": "field.query_text"},
            "limit": {"type": "integer", "required": false, "default": 10, "source": "model", "label_ref": "field.result_limit"},
            "origin": {"type": "geo_point", "required": false, "source": "context", "context_key": "origin"}
          }
        }
      ]
    }
  ],
  "structures": {
    "canonical": [
      "Call",
      "Dataset"
    ],
    "service": []
  },
  "errors": []
}

The service object identifies the Service whose platform interface is being defined.

The contract object identifies the published contract revision.

The invocation object defines the Service base URL used by authorized platform callers.

The authentication object defines Service-level authentication requirements.

The endpoints array defines every platform endpoint exposed by the Service.

The labels object is a flat table of display-copy strings keyed by reference, consumed by argument schemas (see [Labels](#labels)). It is optional only for a Contract with no model-sourced arguments.

The structures object references canonical structures and Service-specific structures used by the contract.

The errors array defines reusable Service-level error semantics.

Endpoint request.structure and response.structure values reference structures by name. They do not inline canonical structure definitions.

Operation Argument Schemas

An endpoint that accepts more than one operation through Call.content.operation shall declare each operation as an object under endpoints[].operations, not as a bare operation-name string. Each operation object shall declare every argument required to correctly invoke that operation.

Every declared argument shall specify:

type — the argument's data type (string, integer, number, boolean, array, or a canonical structure: geo_point — a Runtime renders it as a real map with a pickable or draggable point rather than separate latitude/longitude fields; datetime — a naive wall-clock string with no timezone offset, e.g. 2026-09-16T21:09:20; a Runtime renders it as a real date/time picker rather than free text; or drawing_operation — one Drawing Operation (see canonical/drawing-operation.md) describing a freehand mark. A Runtime renders a model-sourced drawing_operation argument as a live drawing surface — presenting whatever marks the target Object already carries, capturing further pointer or controller input as the member draws, and filling the argument with the resulting operation on submission. As with geo_point and datetime, a Runtime recognizes this treatment from the argument's declared type alone; it does not infer it from the Service id, Object type, operation id, or argument name. This is the only mechanism a Service uses to offer freehand drawing — there is no Service-specific "editor" or "surface" concept a Runtime matches by name (see canonical/object.md, Recognized content format: drawing_surface));
required — whether the argument must be present for the operation to be invoked;
source — where the argument's value originates;
default — the value assumed when the argument is optional and absent, if any.

String arguments may declare a semantic format in constraints.format. The canonical format
markdown means the value is Markdown source intended for long-form editing. A Runtime shall
render a model-sourced Markdown argument with a multiline editor that preserves line breaks; it
shall not infer this treatment from the Service id, Object type, operation id, or argument name.
The Service remains responsible for validating and storing the submitted source. An unformatted
string remains a single-line value unless another canonical format says otherwise.

"body": {
  "type": "string",
  "required": false,
  "source": "model",
  "label_ref": "field.body",
  "constraints": {
    "max_bytes": 1048576,
    "format": "markdown"
  }
}

An argument's source shall be one of:

- model — the value is supplied by whichever caller selected the operation (a reasoning Model's selection, or an explicit operation_invocation.payload). A platform orchestrator never invents a model-sourced value.
- context — the value is resolved by the platform orchestrator itself from the Call's own canonical structure, identified by a context_key naming a canonical, cross-cutting concept. Context-sourced arguments are never asked of a Model and never appear in an operation's Model-facing selectable arguments. The current canonical context-key vocabulary:
- origin — a geographic origin point, resolved from ambient Call content or context.
- member_id — the authenticated member identity resolved by the calling platform service.
- object_id — the object an explicit action targets, resolved from content.operation_invocation.object_id. Every Dataset action already carries its target this way regardless of which Service produced the action, so an operation whose argument identifies "the object this action applies to" (opening, editing, or renaming something already shown to the member) shall use context_key: object_id rather than expecting a Model or an invocation payload to supply it under a different name.

This distinction exists so that a platform orchestrator can invoke any correctly-published Contract generically, without Service-specific code. An orchestrator's context-key vocabulary is a small, fixed, platform-wide set of canonical Call/Context concepts; it is not extended per Service. A Service contract may declare a context argument only using an existing canonical context key. If a Service needs a value that has no existing canonical context key, that value shall be model-sourced instead, or the platform's canonical Call/Context model shall be extended first — a Contract does not invent new context sources unilaterally.

A Contract whose endpoints[].operations entries omit argument schemas, or whose bare operation-name strings are not resolvable to a schema, does not satisfy "all information required to correctly invoke the endpoint" and is not a conforming Service contract.

Every model-sourced argument shall additionally declare a label_ref, and every argument that declares an enum shall declare enum_label_refs — see [Labels](#labels). context-sourced arguments are never presented to a member and take no label refs.

Labels

A generic consumer — a Runtime's form renderer, a reasoning Model weighing candidate operations, a Service Dashboard — needs a human-readable name for every argument it may present and every enumerated value it may offer. That display copy is part of the Service's platform interface and therefore lives in the Contract, in a single top-level labels table, referenced from the argument schemas. It is never inlined on the argument, never humanised from the wire key by the consumer, and never maintained outside the Contract.

labels is a flat object mapping a reference — an arbitrary Contract-local string, conventionally dotted (field.message_privacy, enum.message_privacy.none, help.message_privacy) — to its display string. References carry no meaning to the platform; they are resolved by exact match only.

An argument schema references the table with:

label_ref — the field's own name. Required on every model-sourced argument.
enum_label_refs — an object mapping every value in the argument's enum to a reference. Required whenever enum is declared, and it shall cover every enum value.
help_ref — an optional one-line clarification shown beneath the field. Keep label_ref short and interface-first; put the explanatory sentence that also helps a reasoning Model in help_ref. Do not introduce a separate model-facing description field.

"labels": {
  "field.message_privacy": "Who can message me",
  "help.message_privacy": "Who can start a new message thread with you.",
  "enum.message_privacy.all": "Everyone",
  "enum.message_privacy.connected_only": "Only people in my circles",
  "enum.message_privacy.none": "No one"
},
"endpoints": [{ "operations": [{
  "id": "identity.messaging_preference.update",
  "arguments": {
    "value": {
      "type": "string", "required": true, "source": "model",
      "enum": ["all", "connected_only", "none"],
      "label_ref": "field.message_privacy",
      "help_ref": "help.message_privacy",
      "enum_label_refs": {
        "all": "enum.message_privacy.all",
        "connected_only": "enum.message_privacy.connected_only",
        "none": "enum.message_privacy.none"
      }
    }
  }
}}]}

A platform orchestrator resolves every ref against labels and delivers the flat display text to consumers; a consumer never sees a raw *_ref key and never needs the labels table itself. A ref that does not resolve, a model-sourced argument with no label_ref, an enum value absent from enum_label_refs, or a labels entry that is empty or unreferenced makes the Contract non-conforming. During migration a platform orchestrator records these as warnings and still accepts the Contract; once every registered Service is migrated it rejects them.

The Contract's Markdown representation shall reproduce the labels table so the two representations do not conflict.

Model-Selectable Operations

An operation may declare "model_selectable": false to indicate a reasoning Model shall never select it directly. It defaults to true when omitted; existing Contracts that do not declare it are unaffected.

An operation is marked model_selectable: false when a required argument cannot be honestly supplied by a Model reasoning over a Call alone — most commonly an identifier referring to a specific object the member has not yet indicated (for example a document to edit or delete), where inventing one would mean guessing which object the member means. Such an operation remains reachable only through an explicit operation_invocation, whose target was already established by an earlier Dataset the member acted on (a search result, a list item, an object already open in a Runtime) rather than interpreted from free-form intent.

model_selectable: false does not change how the operation is invoked once selected — its argument schema, sourcing, and validation are identical to any other operation. It changes only whether a platform orchestrator's reasoning Model is ever offered it as a candidate.

Entry Points

A Service contract may declare a top-level entrypoints array naming that Service's meaningful, standalone human entrances — the entrances a generic consumer such as a Service Dashboard should offer, independent of whether a reasoning Model may also reach the same operation from free text.

entrypoints is independent of model_selectable. model_selectable governs whether a reasoning Model may select an operation directly from an unconstrained Call. entrypoints governs whether an operation constitutes a meaningful standalone entrance into the Service for a member. Neither implies the other: an operation may be model_selectable: true without appearing in entrypoints, and an entrypoint's operation need not itself be model_selectable.

Each entry in entrypoints shall declare:

id — a unique string identifying the entry point within the Service contract.
label — a short, human-facing name for the entrance.
purpose — a plain-language description of what the entrance does.
operation — the id of an operation already declared under this contract's endpoints[].operations. An entrypoints entry whose operation does not resolve to a declared operation is not conforming.

Each entry may additionally declare:

arguments — a flat map of preset values merged into the resulting invocation's payload when the entry point is invoked (for example, {"type": "conversation"} to scope an otherwise general-purpose list operation to one kind of result). A platform orchestrator treats these values opaquely, passing them through to the named operation exactly as it would any other caller-supplied model-sourced argument; it does not interpret what a preset field means.
object_types — the object or collection types a member should expect this entrance to surface. Informational: it describes the entrance for documentation and future consumers and is not enforced against the operation's actual response.
primary — whether the Service considers this its default or most prominent entrance. Informational; a Contract with no primary: true entry, or more than one, is still conforming.

A Service contract that declares no entrypoints key, or declares it as an empty array, is fully conforming. entrypoints is additive: existing Contracts that predate this concept remain valid without change.

Canonical Service Publication Shape

Every Service Publication JSON document shall use this top-level shape:

{
  "service": {
    "id": "maps.elonn",
    "name": "Maps",
    "domain": "spatial",
    "description": "Provides geographic, place, route, and spatial information."
  },
  "capabilities": [
    {
      "id": "place_search",
      "description": "Find places from names, categories, locations, or spatial constraints."
    },
    {
      "id": "routing",
      "description": "Determine routes between geographic locations."
    },
    {
      "id": "geography",
      "description": "Provide geographic and spatial information about places."
    }
  ],
  "contract": {
    "json": "https://maps.elonn.com/maps.json",
    "markdown": "https://maps.elonn.com/maps.md",
    "revision": 1
  },
  "published": "2026-08-18T00:00:00Z"
}

The service object identifies and briefly describes the Service.

The capabilities array contains selection descriptions. Capabilities are used by Service Registry and Conductor to decide whether the Service should be considered.

Capability descriptions are not invocation definitions.

The contract object locates the authoritative Service contract representations and identifies the contract revision described by the Publication.

The published value identifies when the Service Publication was published.

Service Publications shall not contain endpoint paths, request schemas, response schemas, authorization rules, privacy rules, side effects, error semantics, Service-specific structures, or operational invocation semantics.

Markdown Representation

The Markdown representation documents the canonical Service contract for human readers.

It describes the same Service contract defined by the canonical JSON representation.

The Markdown representation shall not modify or conflict with the canonical Service contract.

The organization of the Markdown representation is independent of the canonical JSON representation.

Information may be reorganized, repeated, summarized, or cross referenced to improve readability.

Explanatory material, examples, and implementation guidance may be included provided they do not modify the canonical Service contract.

Endpoint Definitions

Every platform endpoint exposed by a Service shall be defined by the Service contract.

An endpoint definition describes a single platform interface exposed by a Service.

Every endpoint definition shall include all information required to correctly invoke the endpoint and interpret its response.

An endpoint definition shall define:

the endpoint;
its purpose;
the request accepted by the endpoint;
the response returned by the endpoint;
authentication requirements;
authorization requirements;
side effects;
privacy considerations;
error conditions; and
references to any canonical or Service-defined structures used by the endpoint.

An endpoint shall be defined once within the canonical JSON representation.

The Markdown representation may organize endpoint information in any manner that improves readability.

Endpoints should be documented independently.

A reader should not be required to consult multiple endpoint definitions to understand the behavior of a single endpoint.

Shared structures, authentication requirements, authorization requirements, and error definitions may be referenced where appropriate.

Related endpoints may be grouped within the Markdown representation to improve discoverability.

The Service contract shall define every platform endpoint exposed by the Service.

Endpoints that are not published in the Service contract are not part of the Service's platform interface.

Canonical Structures

Service contracts use canonical platform structures.

Canonical structures are defined by the Elonn platform.

Service contracts shall reference canonical structures rather than redefining them.

Canonical structures are defined independently of Service contracts.

A Service shall reuse an existing canonical structure whenever one accurately represents the required concept.

The introduction of new canonical structures is governed by the platform's canonical structure policy.

Authentication and Authorization

A Service contract shall define the authentication requirements for communicating with the Service.

Authentication requirements that apply to every endpoint should be defined once at the Service level.

Endpoint-specific authentication requirements shall be defined by the endpoint.

A Service contract shall define the authorization requirements for every endpoint.

Authorization requirements shall identify the permissions, capabilities, or conditions required to successfully invoke an endpoint.

Authentication and authorization policies are defined separately from Service contracts.

---

Errors

A Service contract shall define the errors that may be returned by the Service.

Errors common to multiple endpoints should be defined once and referenced where applicable.

Endpoint-specific errors shall be defined by the endpoint.

Error definitions shall uniquely identify each error and its meaning.

The platform error model is defined separately from Service contracts.

---

Publishing

Every Service shall publish its Service contract in both canonical JSON and Markdown representations.

Every Service shall publish its Service contract at the platform-defined publication endpoints.

The canonical Service contract JSON shall be published at:

https://<service>.elonn.com/<service>.json

The human-readable Service contract Markdown shall be published at:

https://<service>.elonn.com/<service>.md

Every Service shall publish a changelog documenting revisions to its published Service contract.

Every Service shall publish a Service Publication that identifies the Service, describes selectable capabilities, and locates the authoritative Service contract.

The Service Publication shall be published at:

https://<service>.elonn.com/<service>-publication.json

The Service Publication is the authority for deciding whether to consider a Service.

The Service contract is the authority for using a Service.

The Service Registry provides Service discovery by indexing Service Publications. It does not duplicate Service contract contents.

Service Publications shall not define endpoint paths, request schemas, response schemas, authorization rules, privacy rules, side effects, error semantics, Service-specific structures, or operational invocation semantics.

Publication requirements are defined separately from Service contracts.

---

Contract Evolution

Service contracts shall evolve without unnecessarily disrupting existing consumers.

Changes should preserve compatibility whenever practical.

Every published revision of a Service contract shall be documented in the Service changelog.

Changes affecting the platform architecture, canonical structures, or platform policies shall follow the applicable governance process.

Versioning and compatibility policy are defined separately from Service contracts.