@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/localized-content-page.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/localized-content-page.schema.json",
+  "title": "LocalizedContentPage",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). An authored content page: an ordered composition of sections addressed by a URL `slug`. Publication status is atomic across locales for v1. SEO carries hreflang + og:locale alternates so a renderer can emit per-locale link relations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["pageId", "slug", "name", "status", "sectionOrder"],
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the page within its tenant."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "URL slug for public delivery (`GET /v1/content/pages/{slug}`). Lowercase, hyphen-separated."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-facing page name (admin/authoring label)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "published"],
+      "description": "Publication status, atomic across locales for v1. A `draft` page MUST NOT be served on the public delivery path."
+    },
+    "sectionOrder": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Ordered list of `sectionId`s defining the page's render order."
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional SEO metadata for per-locale link relations.",
+      "properties": {
+        "hreflang": {
+          "type": "array",
+          "description": "hreflang alternates: per-locale canonical URLs.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["locale", "href"],
+            "properties": {
+              "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+              "href": { "type": "string", "format": "uri" }
+            }
+          }
+        },
+        "ogLocaleAlternates": {
+          "type": "array",
+          "description": "og:locale:alternate values.",
+          "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/schemas/localized-content-section.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/localized-content-section.schema.json",
+  "title": "LocalizedContentSection",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). One section record of an authored content page. A section is ONE record carrying a base `data` payload (authored in the host's `content.baseLocale`) plus a sparse `localizations` map of partial per-locale field overrides — never one record per locale. The negotiated locale's resolved body is computed by the normative per-section field merge (exact-locale → language-family → base `data`, shallow overlay; §C). Body field shapes inside `data`/`localizations` are open and host/section-type-defined; this schema closes the envelope, not the body.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sectionId", "sectionType", "data", "localizations", "status", "enabled", "order"],
+  "properties": {
+    "sectionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the section within its page."
+    },
+    "sectionType": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The section-type discriminator (e.g. `hero`, `features`). The host/section-type defines the body field shape; the protocol does not."
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The base/default-locale fields, authored in `content.baseLocale`. Open object — body shapes are the host/section-type's concern."
+    },
+    "localizations": {
+      "type": "object",
+      "description": "Sparse map of per-locale partial field overrides. MAY be empty (`{}`). Each key is a BCP-47 tag matching `^[a-z]{2}(-[A-Z]{2})?$` and MUST NOT equal `content.baseLocale` (the base locale is carried by `data`). Each value is a partial overlay of `data` fields; missing fields fall through to `data` (per-section merge §C).",
+      "propertyNames": {
+        "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "Partial field overrides for one locale; shallow-overlaid onto `data`."
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "published"],
+      "description": "Publication status. Atomic across all locales for v1 (no per-locale publish). The public delivery path serves `published` only."
+    },
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether the section participates in delivery when its page is rendered."
+    },
+    "order": {
+      "type": "integer",
+      "description": "Render order of the section within its page (lower first). `sectionOrder` on the page is authoritative; `order` is the per-section tiebreak/sort hint."
+    }
+  }
+}

package/schemas/memory-entry.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/memory-entry.schema.json",
+  "title": "MemoryEntry",
+  "description": "A single memory entry returned by `MemoryAdapter.list` or `MemoryAdapter.get` (RFC 0004). Hosts that ship cross-run memory expose entries in this shape regardless of their internal storage format. Mid-run mutations to the underlying store are NOT visible to the same run — `list` returns entries that existed at run start (preserves replay determinism per RFC 0004 §A).",
+  "type": "object",
+  "required": ["id", "content", "tags", "createdAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Memory entry id. Stable for the lifetime of the entry. Hosts MAY tenant-prefix (`mem_<wsId>_<id>`) for defense in depth, but the protocol is silent on the id shape — see RFC 0004 §Unresolved questions #1. Length cap matches Firestore document-id limit (1500 octets) so adapters that pass-through native Firestore IDs validate cleanly.",
+      "minLength": 1,
+      "maxLength": 1500
+    },
+    "content": {
+      "type": "string",
+      "description": "Memory body. UTF-8 plaintext. Hosts MUST honor the redaction invariant SR-1 (RFC 0004 §D) at write time — content reaching this projection MUST NOT contain plaintext secret values that flowed through the run's BYOK harness."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "maxLength": 256 },
+      "description": "Free-form tags for filtering. Hosts MAY enforce caps. Empty strings are tolerated by the schema (matches reference-impl behavior) but hosts SHOULD filter them at write time. The `MemoryListOptions.tag` filter is a set-membership check against this array. Hosts that want to surface their internal `MemorySource` (or similar host-defined classification) MAY do so via tags (e.g., `tags: ['source:session']`) per RFC 0004 §G."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of entry creation. Never mutated post-create; subsequent edits to the entry are out-of-spec at the read-path layer."
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Optional TTL. When the host's clock passes this value, the entry MUST NOT be returned by `list` / `get`. Hosts MAY also delete expired entries from storage as a side effect."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/memory-list-options.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/memory-list-options.schema.json",
+  "title": "MemoryListOptions",
+  "description": "Options accepted by `MemoryAdapter.list` (RFC 0004). All fields optional; default is \"all entries, newest first.\" Hosts MAY further bound results per their scale-profile.",
+  "type": "object",
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cap on entries returned. `0` means \"no limit\" (treated identically to omission); positive integers cap the result. Hosts MAY further bound the effective cap per their scale-profile. When omitted, the host applies its own default cap (typical: 100 entries)."
+    },
+    "tag": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "Filter to entries whose `tags` array contains this string (set-membership check). Hosts MAY support more advanced filtering as a host extension under a `vendor.<host>.*` field."
+    },
+    "tokenBudget": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "RFC 0113. Max cumulative tokens across returned entries, denominated in the unit named by `capabilities.memory.injectionBudget.tokenCounter`. The adapter MUST return a prefix of the ranked entry list whose cumulative token count does not exceed this; a single entry exceeding the budget on its own MUST be omitted (not truncated mid-entry). MAY combine with `limit` — the adapter honors whichever yields fewer entries. Requires the host to advertise `memory.injectionBudget.supported`."
+    },
+    "rank": {
+      "type": "string",
+      "enum": ["recency", "relevance"],
+      "description": "RFC 0113. Selection order for the (optionally `tokenBudget`-bounded) read. `recency` (default when absent) orders most-recent-first — today's behavior. `relevance` DELEGATES to the existing `memory.search` semantic mode (RFC 0080): it requires `query` AND that the host advertise `capabilities.memory.search` with `semantic` mode, and is the budgeted projection OVER that existing search surface — NOT a new ranking capability. A host that does not advertise `memory.search` semantic mode MUST reject `rank:'relevance'` (or fall back to `'recency'` per its documented behavior)."
+    },
+    "query": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "description": "RFC 0113. Free-text relevance anchor (the `memory.search` semantic query) — REQUIRED when `rank:'relevance'`, ignored otherwise."
+    }
+  },
+  "additionalProperties": false
+}