@rathnasgala2/schemas 2.14.0 → 2.15.0

package/README.md

@@ -91,6 +91,30 @@ calls `postMembershipInvitationsByTokenAccept`; its non-enumerating failure
 states collapse onto that operation's single declared `INVALID_SOURCE_STATE`
 problem, which covers an expired, already-used or unknown token alike.
 
+SCHEMA-2.15.0 closes a Content-list gap SCHEMA-2.14.0 left: with `kind` the only
+fact the inventory carried about a flat file, a row could not show title, kind,
+status or last-changed, and a client could not check web-address uniqueness,
+without one round trip per row. `ContentInventoryItem` gains two optional
+members, exactly one of which the server returns on every item from this version
+on: `summary` (`ContentInventoryItemSummary` --
+`contentId`/`title`/`slug`/`status`/`language`/`createdAt` required,
+`updatedAt`/`publishedAt` optional; `status` is the new closed
+`ContentItemStatus`, `DRAFT`/`PUBLISHED`/`UNLISTED`/`ARCHIVED`) when the header
+block the server now reads for every listed path parses, or `unreadable`
+(`ContentInventoryItemUnreadable`, `{reason}`, the new closed
+`ContentItemUnreadableReason`: `HEADER_MISSING`/`HEADER_UNPARSABLE`/
+`HEADER_INVALID`/`TOO_LARGE`) when it does not. `kind` itself now comes from the
+header when `summary` is present, from the content root as before when it is
+not. This is stated in the operation description rather than schema- enforced,
+because a `oneOf` requiring one of the two would make a pre-2.15.0 item -- one
+with neither field, valid until now -- invalid; member types reuse
+`content-frontmatter.schema.json`'s `$defs`, matching how
+`ContentFrontmatter`/`ContentPublicationSummary` already do. `GET .../content`
+also gains its own `limit` bound (`ContentLimit`): default 50 in place of the
+shared default of 25, the existing 100 maximum kept unchanged since lowering a
+maximum is never additive; the server may return fewer items than `limit` even
+when more are available.
+
 SCHEMA-2.14.0 (design `scrap/20260928_write-preview-publish.md` section 3) is
 additive, closing the write/preview/publish content journey. Nine operations
 join the contract under

package/THIRD_PARTY_LICENSES.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "package": "@rathnasgala2/schemas@2.14.0",
+  "package": "@rathnasgala2/schemas@2.15.0",
   "source": "package-lock.json",
   "dependencies": [
     {

package/docs/catalogs/schema-inventory.json

@@ -209,9 +209,9 @@
       "version": "2.0.0",
       "path": "openapi/openapi.yaml",
       "materialized": true,
-      "sourceDigest": "sha256:e8c2073c001219a158d458455a8f238c96ce3b7fdb1eb76bcc04388bcf3cc20d",
+      "sourceDigest": "sha256:ca5cf80a6fc7b91e4a029d9962efc0da84b31a267b0e1a7bbaaba731d426dffc",
       "typescriptRootType": null
     }
   ],
-  "digest": "sha256:90e1849ad012f5c649992cde222da04be4e46fcb04fd3de337f4abf866dffed7"
+  "digest": "sha256:fe8e29466fbeaafd38b28e6d09f94a4f9e05045aaa4af954431d5b493a13ba14"
 }

package/openapi/http-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "2.0.0",
   "sourceDesignRevision": "a53052955ceb6c1aa10c886289dc832eedfe6de0a00004df07d353ac19c4403a",
-  "openApiDigest": "sha256:e8c2073c001219a158d458455a8f238c96ce3b7fdb1eb76bcc04388bcf3cc20d",
+  "openApiDigest": "sha256:ca5cf80a6fc7b91e4a029d9962efc0da84b31a267b0e1a7bbaaba731d426dffc",
   "operations": [
     {
       "operationId": "getInternalHealth",
@@ -1049,5 +1049,5 @@
       "sourceFragment": "workloads"
     }
   ],
-  "digest": "sha256:abcc06359b67cd9c829bb98687ae3b691fe98b2ba2ea1b23272f5a861c21e41c"
+  "digest": "sha256:f4c2d4b69632958faefc39a1a229877a70a60b86a22b9e891bbecb1924878c68"
 }

package/openapi/openapi.yaml

@@ -46,6 +46,20 @@ components:
         pattern: ^(?:sha1:[0-9a-f]{40}|sha256:[0-9a-f]{64})$
         type: string
   parameters:
+    ContentLimit:
+      description: |
+        Same bound as the shared `Limit` parameter, with a higher default
+        appropriate to a content list row: the server may return fewer items
+        than `limit` even when more are available.
+      example: 1
+      in: query
+      name: limit
+      required: false
+      schema:
+        default: 50
+        maximum: 100
+        minimum: 1
+        type: integer
     Cursor:
       example: example
       in: query
@@ -369,6 +383,12 @@ components:
       $ref: "#/components/schemas/PortableContentFrontmatterDocument"
     ContentInventoryItem:
       additionalProperties: false
+      description: |
+        Exactly one of `summary` or `unreadable` is present on every item the
+        server returns from schema 2.15.0 on; a strict validator does not
+        enforce this (it would make an older item with neither field, valid
+        before 2.15.0, invalid), so a reader checks for both being absent
+        defensively.
       properties:
         blobId:
           pattern: ^(?:sha1:[0-9a-f]{40}|sha256:[0-9a-f]{64})$
@@ -384,18 +404,86 @@ components:
           format: int64
           minimum: 0
           type: integer
+        summary:
+          $ref: "#/components/schemas/ContentInventoryItemSummary"
+        unreadable:
+          $ref: "#/components/schemas/ContentInventoryItemUnreadable"
       required:
         - path
         - kind
         - blobId
         - size
       type: object
+    ContentInventoryItemSummary:
+      additionalProperties: false
+      description: |
+        The header block's own facts about this item, read at inventory time.
+        `contentId` is the header's `id`; `status` is the header's `status`
+        upper-cased to this contract's enum style.
+      properties:
+        contentId:
+          $ref: "#/components/schemas/PortableContentFrontmatterStableId"
+        createdAt:
+          $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
+        language:
+          $ref: "#/components/schemas/PortableContentFrontmatterBcp47"
+        publishedAt:
+          $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
+        slug:
+          $ref: "#/components/schemas/PortableContentFrontmatterSlug"
+        status:
+          $ref: "#/components/schemas/ContentItemStatus"
+        title:
+          $ref: "#/components/schemas/PortableContentFrontmatterPlainText"
+          x-gala-graphemeLength:
+            maximum: 200
+            minimum: 1
+        updatedAt:
+          $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
+      required:
+        - contentId
+        - title
+        - slug
+        - status
+        - language
+        - createdAt
+      type: object
+    ContentInventoryItemUnreadable:
+      additionalProperties: false
+      properties:
+        reason:
+          $ref: "#/components/schemas/ContentItemUnreadableReason"
+      required:
+        - reason
+      type: object
     ContentItemKind:
-      description: Which declared content root a document lives under -- ARTICLE for `content/articles/`, PAGE for `content/pages/` -- derived from the path, never from parsing the file.
+      description: Which content root a document lives under -- ARTICLE for `content/articles/`, PAGE for `content/pages/`. Since schema 2.15.0 this comes from the header's own `kind` when the inventory item's `summary` is present; before that, and whenever `unreadable` is present instead, it is derived from the path alone.
       enum:
         - ARTICLE
         - PAGE
       type: string
+    ContentItemStatus:
+      description: The header's `status`, upper-cased to this contract's enum style.
+      enum:
+        - DRAFT
+        - PUBLISHED
+        - UNLISTED
+        - ARCHIVED
+      type: string
+    ContentItemUnreadableReason:
+      description: |
+        Why an inventory item's header could not be read. `HEADER_MISSING`:
+        the file has no header block at all. `HEADER_UNPARSABLE`: the header
+        block does not parse. `HEADER_INVALID`: it parses but does not
+        validate against `content-frontmatter.schema.json`. `TOO_LARGE`: the
+        file exceeds the document read's 1 MiB bound, so the header was never
+        read.
+      enum:
+        - HEADER_MISSING
+        - HEADER_UNPARSABLE
+        - HEADER_INVALID
+        - TOO_LARGE
+      type: string
     ContentPublicationAuthorSummary:
       additionalProperties: false
       properties:
@@ -19901,12 +19989,22 @@ paths:
     get:
       description: |
         One git-trees read per declared content root at the linked repository's
-        current main branch head, bounded at 2,000 entries with no file bodies
-        read. `kind` is derived from which declared content root a path is
-        under (ARTICLE for `content/articles/`, PAGE for `content/pages/`), not
-        from parsing the file. `setUp` reports whether `gala/repository.json`
-        is present on main, matching `GET .../repository/setup`'s `state`.
-        `publication` is read from the settings files
+        current main branch head, bounded at 2,000 entries. For each listed
+        path the server additionally reads that file's header block (bounded,
+        from the person's repository, nothing stored) to fill `summary`.
+        Exactly one of `summary` or `unreadable` is present on every item this
+        operation returns from schema 2.15.0 on: `summary` when the header
+        parses, `unreadable` (with a closed `reason`) when it does not or the
+        file exceeds the read bound. `kind` comes from the header's own
+        `kind` when `summary` is present, and from which declared content
+        root the path is under (ARTICLE for `content/articles/`, PAGE for
+        `content/pages/`) when it is not. `limit` defaults to 50 here (the
+        shared default is 25) because a content list row needs more per
+        round trip than most lists; the server may return fewer items than
+        `limit` even when more are available. `setUp` reports whether
+        `gala/repository.json` is present on main, matching
+        `GET .../repository/setup`'s `state`. `publication` is read from the
+        settings files
         (`gala/repository.json`, `gala/appearance.json`, `gala/authors/`) at
         this same main-branch head, and is returned on every page of the
         inventory, not only the first, so the editor has these facts
@@ -19932,7 +20030,7 @@ paths:
             pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
             type: string
         - $ref: "#/components/parameters/Cursor"
-        - $ref: "#/components/parameters/Limit"
+        - $ref: "#/components/parameters/ContentLimit"
       responses:
         "200":
           content:
@@ -19944,7 +20042,24 @@ paths:
                     defaultBranch: main
                     hasMore: false
                     head: sha1:0000000000000000000000000000000000000000
-                    items: []
+                    items:
+                      - blobId: sha1:0000000000000000000000000000000000000000
+                        kind: ARTICLE
+                        path: content/articles/example.md
+                        size: 128
+                        summary:
+                          contentId: 018f0000-0000-7000-8000-000000000001
+                          createdAt: "2026-09-28T00:00:00.000Z"
+                          language: en
+                          slug: example
+                          status: DRAFT
+                          title: Example
+                      - blobId: sha1:0000000000000000000000000000000000000000
+                        kind: ARTICLE
+                        path: content/articles/unreadable.md
+                        size: 2097152
+                        unreadable:
+                          reason: TOO_LARGE
                     publication:
                       authors:
                         - displayName: Example Author

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala2/schemas",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Executable JSON Schema and OpenAPI contracts for Galascribe",
   "type": "module",
   "license": "Apache-2.0",

package/sbom.cdx.json

@@ -97,8 +97,8 @@
       "type": "library",
       "name": "schemas",
       "group": "@rathnasgala2",
-      "version": "2.14.0",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0",
+      "version": "2.15.0",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0",
       "description": "Executable JSON Schema and OpenAPI contracts for Galascribe",
       "licenses": [
         {
@@ -108,7 +108,7 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40rathnasgala2/schemas@2.14.0?vcs_url=git%2Bhttps%3A%2F%2Fgithub.com%2Frathnasgala2%2Fschema.git",
+      "purl": "pkg:npm/%40rathnasgala2/schemas@2.15.0?vcs_url=git%2Bhttps%3A%2F%2Fgithub.com%2Frathnasgala2%2Fschema.git",
       "externalReferences": [
         {
           "url": "https://github.com/rathnasgala2/schema/issues",
@@ -153,7 +153,7 @@
       "type": "library",
       "name": "ajv-formats",
       "version": "3.0.1",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0|ajv-formats@3.0.1",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0|ajv-formats@3.0.1",
       "licenses": [
         {
           "license": {
@@ -187,7 +187,7 @@
       "type": "library",
       "name": "ajv",
       "version": "8.20.0",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0|ajv@8.20.0",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0|ajv@8.20.0",
       "licenses": [
         {
           "license": {
@@ -221,7 +221,7 @@
       "type": "library",
       "name": "fast-deep-equal",
       "version": "3.1.3",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0|fast-deep-equal@3.1.3",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0|fast-deep-equal@3.1.3",
       "licenses": [
         {
           "license": {
@@ -255,7 +255,7 @@
       "type": "library",
       "name": "fast-uri",
       "version": "3.1.7",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0|fast-uri@3.1.7",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0|fast-uri@3.1.7",
       "licenses": [
         {
           "license": {
@@ -289,7 +289,7 @@
       "type": "library",
       "name": "json-schema-traverse",
       "version": "1.0.0",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0|json-schema-traverse@1.0.0",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0|json-schema-traverse@1.0.0",
       "licenses": [
         {
           "license": {
@@ -323,7 +323,7 @@
       "type": "library",
       "name": "require-from-string",
       "version": "2.0.2",
-      "bom-ref": "@rathnasgala2/schemas@2.14.0|require-from-string@2.0.2",
+      "bom-ref": "@rathnasgala2/schemas@2.15.0|require-from-string@2.0.2",
       "licenses": [
         {
           "license": {
@@ -1064,10 +1064,10 @@
   ],
   "dependencies": [
     {
-      "ref": "@rathnasgala2/schemas@2.14.0",
+      "ref": "@rathnasgala2/schemas@2.15.0",
       "dependsOn": [
-        "@rathnasgala2/schemas@2.14.0|ajv-formats@3.0.1",
-        "@rathnasgala2/schemas@2.14.0|ajv@8.20.0",
+        "@rathnasgala2/schemas@2.15.0|ajv-formats@3.0.1",
+        "@rathnasgala2/schemas@2.15.0|ajv@8.20.0",
         "pkg:npm/semver@7.8.5",
         "urn:gala:source-data:iana-ipv4-special-registry",
         "urn:gala:source-data:iana-ipv6-special-registry",
@@ -1089,31 +1089,31 @@
       ]
     },
     {
-      "ref": "@rathnasgala2/schemas@2.14.0|ajv-formats@3.0.1",
+      "ref": "@rathnasgala2/schemas@2.15.0|ajv-formats@3.0.1",
       "dependsOn": [
-        "@rathnasgala2/schemas@2.14.0|ajv@8.20.0"
+        "@rathnasgala2/schemas@2.15.0|ajv@8.20.0"
       ]
     },
     {
-      "ref": "@rathnasgala2/schemas@2.14.0|ajv@8.20.0",
+      "ref": "@rathnasgala2/schemas@2.15.0|ajv@8.20.0",
       "dependsOn": [
-        "@rathnasgala2/schemas@2.14.0|fast-deep-equal@3.1.3",
-        "@rathnasgala2/schemas@2.14.0|fast-uri@3.1.7",
-        "@rathnasgala2/schemas@2.14.0|json-schema-traverse@1.0.0",
-        "@rathnasgala2/schemas@2.14.0|require-from-string@2.0.2"
+        "@rathnasgala2/schemas@2.15.0|fast-deep-equal@3.1.3",
+        "@rathnasgala2/schemas@2.15.0|fast-uri@3.1.7",
+        "@rathnasgala2/schemas@2.15.0|json-schema-traverse@1.0.0",
+        "@rathnasgala2/schemas@2.15.0|require-from-string@2.0.2"
       ]
     },
     {
-      "ref": "@rathnasgala2/schemas@2.14.0|fast-deep-equal@3.1.3"
+      "ref": "@rathnasgala2/schemas@2.15.0|fast-deep-equal@3.1.3"
     },
     {
-      "ref": "@rathnasgala2/schemas@2.14.0|fast-uri@3.1.7"
+      "ref": "@rathnasgala2/schemas@2.15.0|fast-uri@3.1.7"
     },
     {
-      "ref": "@rathnasgala2/schemas@2.14.0|json-schema-traverse@1.0.0"
+      "ref": "@rathnasgala2/schemas@2.15.0|json-schema-traverse@1.0.0"
     },
     {
-      "ref": "@rathnasgala2/schemas@2.14.0|require-from-string@2.0.2"
+      "ref": "@rathnasgala2/schemas@2.15.0|require-from-string@2.0.2"
     },
     {
       "ref": "pkg:npm/semver@7.8.5"