@rathnasgala2/schemas 3.18.0 → 3.19.0

package/generated/typescript/contracts/content-frontmatter.d.ts

@@ -53,6 +53,8 @@ export type ContentFrontmatterPlainLabel = string;
 
 export type ContentFrontmatterPlainText = string;
 
+export type ContentFrontmatterPublishAfterDate = string;
+
 export type ContentFrontmatterRepoRelativePath = string;
 
 export type ContentFrontmatterRfc3339 = string;
@@ -80,6 +82,7 @@ export type ContentFrontmatterDocument = Readonly<{
   readonly kind: 'article' | 'page' | 'edition';
   readonly language: ContentFrontmatterBcp47;
   readonly newsletter?: 'ineligible' | 'eligible';
+  readonly publishAfter?: ContentFrontmatterPublishAfterDate;
   readonly publishedAt?: ContentFrontmatterRfc3339;
   readonly redirects: ReadonlyArray<ContentFrontmatterCanonicalRoute>;
   readonly route?: ContentFrontmatterCanonicalRoute;

package/openapi/http-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "2.0.0",
   "sourceDesignRevision": "a53052955ceb6c1aa10c886289dc832eedfe6de0a00004df07d353ac19c4403a",
-  "openApiDigest": "sha256:873e58c1c5cff984dbee260f215f8c6f3fd10c8623889ba4618b832814b043a9",
+  "openApiDigest": "sha256:d835a5a348edb96e2c92b3705d038a6854386aa12f6856493214a15493068dde",
   "operations": [
     {
       "operationId": "getInternalHealth",
@@ -2699,5 +2699,5 @@
       "sourceFragment": "workloads"
     }
   ],
-  "digest": "sha256:7c2a102c264904a42607e573f34c5c4db46e498fc068c3778e2b5f8c9f023607"
+  "digest": "sha256:2d26250d96a503479216501c5aa63e1de98fc77276433294d79db1f30fe5f8b8"
 }

package/openapi/openapi.yaml

@@ -1308,7 +1308,9 @@ components:
       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.
+        upper-cased to this contract's enum style. `publishAfter`
+        (SCHEMA-3.19.0, optional and nullable) is the header's staggered-release
+        date.
       properties:
         contentId:
           $ref: "#/components/schemas/PortableContentFrontmatterStableId"
@@ -1316,6 +1318,11 @@ components:
           $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
         language:
           $ref: "#/components/schemas/PortableContentFrontmatterBcp47"
+        publishAfter:
+          description: "SCHEMA-3.19.0: the header's `publishAfter` date (`YYYY-MM-DD`) of a draft waiting for staggered release, `null` or absent when the header carries none."
+          oneOf:
+            - $ref: "#/components/schemas/PortableContentFrontmatterPublishAfterDate"
+            - type: "null"
         publishedAt:
           $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
         slug:
@@ -3738,7 +3745,7 @@ components:
           then:
             required:
               - publishing
-      description: Everything a Home screen needs in one read. `url` is the live site address, `null` when nothing has been published. `lastPublished` is absent when `state` is `NEVER_PUBLISHED`. `publishing` is present exactly while `state` is `PUBLISHING`. `schedule` (SCHEMA-3.3.0, optional) is present while a scheduled publish is pending; a pending schedule never makes `state` `PUBLISHING` -- the site reads as it would without it until the schedule starts.
+      description: Everything a Home screen needs in one read. `url` is the live site address, `null` when nothing has been published. `lastPublished` is absent when `state` is `NEVER_PUBLISHED`. `publishing` is present exactly while `state` is `PUBLISHING`. `schedule` (SCHEMA-3.3.0, optional) is present while a scheduled publish is pending; a pending schedule never makes `state` `PUBLISHING` -- the site reads as it would without it until the schedule starts. `nextRelease` (SCHEMA-3.19.0, optional and nullable) is the scheduled draft that the staggered release will publish next, the one with the earliest `publishAfter` date; `null` or absent when there is none.
       properties:
         attention:
           items:
@@ -3747,6 +3754,10 @@ components:
           type: array
         lastPublished:
           $ref: "#/components/schemas/SiteLastPublished"
+        nextRelease:
+          oneOf:
+            - $ref: "#/components/schemas/SiteNextRelease"
+            - type: "null"
         pendingChanges:
           items:
             $ref: "#/components/schemas/SitePendingChange"
@@ -6961,6 +6972,34 @@ components:
               type: boolean
             requireReview:
               type: boolean
+            staggeredRelease:
+              additionalProperties: false
+              allOf:
+                - if:
+                    properties:
+                      enabled:
+                        not:
+                          enum:
+                            - false
+                        type: boolean
+                        x-gala-const: true
+                    required:
+                      - enabled
+                  then:
+                    required:
+                      - timezone
+              description: "SCHEMA-3.19.0: a change to the staggered-release setting (the shape of `StaggeredReleaseSetting` as a partial update). An omitted `staggeredRelease` leaves the setting unchanged. `timezone` is required when `enabled` is true. When `enabled` is false it may be omitted (the stored zone is kept) or sent (the zone is stored for the next time the setting is turned on). Turning the setting off never edits a draft: its `publishAfter` stays in the file."
+              properties:
+                enabled:
+                  type: boolean
+                timezone:
+                  description: An IANA time zone name, as `StaggeredReleaseTimezone`. An unknown name is `422 VALIDATION_FAILED` pointed at `/publishingPolicy/staggeredRelease/timezone`.
+                  maxLength: 64
+                  pattern: ^(?:[A-Za-z_]+(?:/[A-Za-z0-9_+-]+)+|UTC)$
+                  type: string
+              required:
+                - enabled
+              type: object
           type: object
         slug:
           maxLength: 80
@@ -8163,6 +8202,8 @@ components:
           enum:
             - ineligible
             - eligible
+        publishAfter:
+          $ref: "#/components/schemas/PortableContentFrontmatterPublishAfterDate"
         publishedAt:
           $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
         redirects:
@@ -8292,6 +8333,10 @@ components:
       description: NFC Unicode text without disallowed C0/C1 controls or bidi override/isolate controls.
       format: gala-plain-text
       type: string
+    PortableContentFrontmatterPublishAfterDate:
+      description: "SCHEMA-3.19.0: the calendar date (`YYYY-MM-DD`, day precision, read in the publication's staggered-release timezone) on or after which Galascribe publishes this draft. Meaningful only while `status` is `draft`; Galascribe removes it when the post is published. The API enforces both rules; the schema only fixes the shape."
+      pattern: ^\d{4}-\d{2}-\d{2}$
+      type: string
     PortableContentFrontmatterRepoRelativePath:
       description: NFC UTF-8 repository-relative path using slash separators, with no leading slash, dot segment, NUL, backslash, or percent-decoded traversal.
       format: gala-repository-relative-path
@@ -14861,6 +14906,11 @@ components:
         `appearance`, counting as one of the named members: it edits
         `gala/publication.json` through one planned `PUT` (see
         `ContentChangePublicationProfileEntry`).
+        A `PUT` document whose front matter sets or changes `publishAfter`
+        (SCHEMA-3.19.0) is refused with `409 STAGGERED_RELEASE_DISABLED` while the
+        publication's staggered release is off (`publishingPolicy.staggeredRelease`), and
+        with `422 PUBLISH_AFTER_ON_PUBLISHED_POST` when its `status` is not
+        `draft`; `errors[].pointer` is `/documents/<path>`.
         Assets are images only (PNG, JPEG, WebP, GIF, AVIF; SVG is refused):
         at most 20 per change, each at most 5 MiB and together at most
         20 MiB, measured on the decoded bytes -- `assets[].bytesBase64` is
@@ -17511,7 +17561,7 @@ components:
       type: string
     PublishingPolicy:
       additionalProperties: false
-      description: "How this publication publishes. Absence of the member on the publication resource means the defaults: `requireReview` false, `galascribeMerges` true."
+      description: "How this publication publishes. Absence of the member on the publication resource means the defaults: `requireReview` false, `galascribeMerges` true, and `staggeredRelease` off (`enabled` false, `timezone` null). When the member is present it carries all three (SCHEMA-3.19.0 adds `staggeredRelease`)."
       properties:
         galascribeMerges:
           description: Default true. When true Galascribe opens and merges the pull request itself through the GitHub App; when false each change must already be merged on GitHub before it can be published.
@@ -17519,9 +17569,12 @@ components:
         requireReview:
           description: Default false. When true a change needs an approved review before it can be published.
           type: boolean
+        staggeredRelease:
+          $ref: "#/components/schemas/StaggeredReleaseSetting"
       required:
         - requireReview
         - galascribeMerges
+        - staggeredRelease
       type: object
     PutOrganizationsByOrganizationIdPublicationsByPublicationIdAnalyticsSettingsRequest:
       additionalProperties: false
@@ -19147,6 +19200,18 @@ components:
         - at
         - actor
       type: object
+    SiteNextRelease:
+      additionalProperties: false
+      description: "The next draft the staggered release will publish (SCHEMA-3.19.0): `slug` is the draft's slug and `publishAfter` its `YYYY-MM-DD` date, read in the publication's staggered-release timezone."
+      properties:
+        publishAfter:
+          $ref: "#/components/schemas/PortableContentFrontmatterPublishAfterDate"
+        slug:
+          $ref: "#/components/schemas/PortableContentFrontmatterSlug"
+      required:
+        - slug
+        - publishAfter
+      type: object
     SitePendingChange:
       additionalProperties: false
       allOf:
@@ -19347,6 +19412,40 @@ components:
         - from
         - to
       type: object
+    StaggeredReleaseSetting:
+      additionalProperties: false
+      allOf:
+        - if:
+            properties:
+              enabled:
+                not:
+                  enum:
+                    - false
+                type: boolean
+                x-gala-const: true
+            required:
+              - enabled
+          then:
+            properties:
+              timezone:
+                type: string
+      description: "SCHEMA-3.19.0: the publication's staggered-release setting as stored, the `staggeredRelease` member of `PublishingPolicy`. When `enabled` is true Galascribe publishes each draft whose `publishAfter` front-matter date has arrived, reading the date in `timezone` and releasing it on the first sweep at or after 00:00 of that date; when false nothing is released by the system and `publishAfter` values are kept untouched. A publication that never set it reads `{enabled: false, timezone: null}`; `timezone` is never null while `enabled` is true."
+      properties:
+        enabled:
+          type: boolean
+        timezone:
+          oneOf:
+            - $ref: "#/components/schemas/StaggeredReleaseTimezone"
+            - type: "null"
+      required:
+        - enabled
+        - timezone
+      type: object
+    StaggeredReleaseTimezone:
+      description: "SCHEMA-3.19.0: an IANA time zone name (`America/Los_Angeles`, `Europe/London`, `UTC`). The API accepts only a name its time-zone database knows; an unknown name is `422 VALIDATION_FAILED` pointed at `/publishingPolicy/staggeredRelease/timezone`. The pattern only fixes the shape."
+      maxLength: 64
+      pattern: ^(?:[A-Za-z_]+(?:/[A-Za-z0-9_+-]+)+|UTC)$
+      type: string
     VerificationPlanEntry:
       additionalProperties: false
       properties:
@@ -31971,7 +32070,7 @@ paths:
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
     patch:
       description: |
-        Updates publication metadata and state. As of schema 2.22.0 the request may also carry `publishingPolicy` (`requireReview`, `galascribeMerges`), a partial update: an omitted member keeps its value. The publication resource (`GET` and this response) returns `publishingPolicy`; its absence means the defaults, `requireReview` false and `galascribeMerges` true. The policy governs `POST .../changes:publish` and the review of changes.
+        Updates publication metadata and state. As of schema 2.22.0 the request may also carry `publishingPolicy` (`requireReview`, `galascribeMerges`), a partial update: an omitted member keeps its value. The publication resource (`GET` and this response) returns `publishingPolicy`; its absence means the defaults, `requireReview` false and `galascribeMerges` true. The policy governs `POST .../changes:publish` and the review of changes. SCHEMA-3.19.0 adds `publishingPolicy.staggeredRelease` (`enabled`, `timezone`): staggered release publishes each draft whose `publishAfter` front-matter date has arrived, reading the date in `timezone`. A present `publishingPolicy` always carries it (a publication that never set it reads `enabled` false and `timezone` null; the absence of `publishingPolicy` means the same). In the request it is optional, absent means unchanged, `timezone` is required when `enabled` is true and must be an IANA zone name, else `422 VALIDATION_FAILED` pointed at `/publishingPolicy/staggeredRelease/timezone`.
       operationId: patchOrganizationsByOrganizationIdPublicationsByPublicationId
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -34422,6 +34521,21 @@ paths:
                     status: 409
                     title: INVALID_SOURCE_STATE
                     type: urn:gala:problem:invalid-source-state
+                STAGGERED_RELEASE_DISABLED:
+                  summary: STAGGERED_RELEASE_DISABLED
+                  value:
+                    code: STAGGERED_RELEASE_DISABLED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: A document carries publishAfter but the publication's staggered release is off. See the operation contract.
+                    errors:
+                      - code: STAGGERED_RELEASE_DISABLED
+                        pointer: /documents/content~1articles~1example.md
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: STAGGERED_RELEASE_DISABLED
+                    type: urn:gala:problem:staggered-release-disabled
                 TRANSFER_PENDING:
                   summary: TRANSFER_PENDING
                   value:
@@ -34437,7 +34551,7 @@ paths:
                     type: urn:gala:problem:transfer-pending
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: COMMAND_REPLAY_CONFLICT, INVALID_SOURCE_STATE, TRANSFER_PENDING
+          description: COMMAND_REPLAY_CONFLICT, INVALID_SOURCE_STATE, STAGGERED_RELEASE_DISABLED, TRANSFER_PENDING
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
@@ -34448,11 +34562,27 @@ paths:
           x-gala-problem-codes:
             - COMMAND_REPLAY_CONFLICT
             - INVALID_SOURCE_STATE
+            - STAGGERED_RELEASE_DISABLED
             - TRANSFER_PENDING
         "422":
           content:
             application/problem+json:
               examples:
+                PUBLISH_AFTER_ON_PUBLISHED_POST:
+                  summary: PUBLISH_AFTER_ON_PUBLISHED_POST
+                  value:
+                    code: PUBLISH_AFTER_ON_PUBLISHED_POST
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: A document carries publishAfter but its status is not draft. See the operation contract.
+                    errors:
+                      - code: PUBLISH_AFTER_ON_PUBLISHED_POST
+                        pointer: /documents/content~1articles~1example.md
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 422
+                    title: PUBLISH_AFTER_ON_PUBLISHED_POST
+                    type: urn:gala:problem:publish-after-on-published-post
                 VALIDATION_FAILED:
                   summary: VALIDATION_FAILED
                   value:
@@ -34468,13 +34598,14 @@ paths:
                     type: urn:gala:problem:validation-failed
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: VALIDATION_FAILED
+          description: PUBLISH_AFTER_ON_PUBLISHED_POST, VALIDATION_FAILED
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
+            - PUBLISH_AFTER_ON_PUBLISHED_POST
             - VALIDATION_FAILED
         "503":
           content:
@@ -34525,8 +34656,10 @@ paths:
         - CAPABILITY_UNAVAILABLE
         - COMMAND_REPLAY_CONFLICT
         - INVALID_SOURCE_STATE
+        - PUBLISH_AFTER_ON_PUBLISHED_POST
         - REQUEST_FIELD_UNKNOWN
         - RESOURCE_NOT_FOUND
+        - STAGGERED_RELEASE_DISABLED
         - TRANSFER_PENDING
         - VALIDATION_FAILED
       x-gala-replay-identity: idempotency-key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala2/schemas",
-  "version": "3.18.0",
+  "version": "3.19.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": "3.18.0",
-      "bom-ref": "@rathnasgala2/schemas@3.18.0",
+      "version": "3.19.0",
+      "bom-ref": "@rathnasgala2/schemas@3.19.0",
       "description": "Executable JSON Schema and OpenAPI contracts for Galascribe",
       "licenses": [
         {
@@ -108,7 +108,7 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40rathnasgala2/schemas@3.18.0?vcs_url=git%2Bhttps%3A%2F%2Fgithub.com%2Frathnasgala2%2Fschema.git",
+      "purl": "pkg:npm/%40rathnasgala2/schemas@3.19.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@3.18.0|ajv-formats@3.0.1",
+      "bom-ref": "@rathnasgala2/schemas@3.19.0|ajv-formats@3.0.1",
       "licenses": [
         {
           "license": {
@@ -187,7 +187,7 @@
       "type": "library",
       "name": "ajv",
       "version": "8.20.0",
-      "bom-ref": "@rathnasgala2/schemas@3.18.0|ajv@8.20.0",
+      "bom-ref": "@rathnasgala2/schemas@3.19.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@3.18.0|fast-deep-equal@3.1.3",
+      "bom-ref": "@rathnasgala2/schemas@3.19.0|fast-deep-equal@3.1.3",
       "licenses": [
         {
           "license": {
@@ -255,7 +255,7 @@
       "type": "library",
       "name": "fast-uri",
       "version": "3.1.8",
-      "bom-ref": "@rathnasgala2/schemas@3.18.0|fast-uri@3.1.8",
+      "bom-ref": "@rathnasgala2/schemas@3.19.0|fast-uri@3.1.8",
       "licenses": [
         {
           "license": {
@@ -289,7 +289,7 @@
       "type": "library",
       "name": "json-schema-traverse",
       "version": "1.0.0",
-      "bom-ref": "@rathnasgala2/schemas@3.18.0|json-schema-traverse@1.0.0",
+      "bom-ref": "@rathnasgala2/schemas@3.19.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@3.18.0|require-from-string@2.0.2",
+      "bom-ref": "@rathnasgala2/schemas@3.19.0|require-from-string@2.0.2",
       "licenses": [
         {
           "license": {
@@ -1064,10 +1064,10 @@
   ],
   "dependencies": [
     {
-      "ref": "@rathnasgala2/schemas@3.18.0",
+      "ref": "@rathnasgala2/schemas@3.19.0",
       "dependsOn": [
-        "@rathnasgala2/schemas@3.18.0|ajv-formats@3.0.1",
-        "@rathnasgala2/schemas@3.18.0|ajv@8.20.0",
+        "@rathnasgala2/schemas@3.19.0|ajv-formats@3.0.1",
+        "@rathnasgala2/schemas@3.19.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@3.18.0|ajv-formats@3.0.1",
+      "ref": "@rathnasgala2/schemas@3.19.0|ajv-formats@3.0.1",
       "dependsOn": [
-        "@rathnasgala2/schemas@3.18.0|ajv@8.20.0"
+        "@rathnasgala2/schemas@3.19.0|ajv@8.20.0"
       ]
     },
     {
-      "ref": "@rathnasgala2/schemas@3.18.0|ajv@8.20.0",
+      "ref": "@rathnasgala2/schemas@3.19.0|ajv@8.20.0",
       "dependsOn": [
-        "@rathnasgala2/schemas@3.18.0|fast-deep-equal@3.1.3",
-        "@rathnasgala2/schemas@3.18.0|fast-uri@3.1.8",
-        "@rathnasgala2/schemas@3.18.0|json-schema-traverse@1.0.0",
-        "@rathnasgala2/schemas@3.18.0|require-from-string@2.0.2"
+        "@rathnasgala2/schemas@3.19.0|fast-deep-equal@3.1.3",
+        "@rathnasgala2/schemas@3.19.0|fast-uri@3.1.8",
+        "@rathnasgala2/schemas@3.19.0|json-schema-traverse@1.0.0",
+        "@rathnasgala2/schemas@3.19.0|require-from-string@2.0.2"
       ]
     },
     {
-      "ref": "@rathnasgala2/schemas@3.18.0|fast-deep-equal@3.1.3"
+      "ref": "@rathnasgala2/schemas@3.19.0|fast-deep-equal@3.1.3"
     },
     {
-      "ref": "@rathnasgala2/schemas@3.18.0|fast-uri@3.1.8"
+      "ref": "@rathnasgala2/schemas@3.19.0|fast-uri@3.1.8"
     },
     {
-      "ref": "@rathnasgala2/schemas@3.18.0|json-schema-traverse@1.0.0"
+      "ref": "@rathnasgala2/schemas@3.19.0|json-schema-traverse@1.0.0"
     },
     {
-      "ref": "@rathnasgala2/schemas@3.18.0|require-from-string@2.0.2"
+      "ref": "@rathnasgala2/schemas@3.19.0|require-from-string@2.0.2"
     },
     {
       "ref": "pkg:npm/semver@7.8.5"

package/schemas/content-frontmatter.schema.json

@@ -65,6 +65,7 @@
     "newsletter": { "enum": ["ineligible", "eligible"] },
     "edition": { "$ref": "#/$defs/contentEdition" },
     "seo": { "$ref": "#/$defs/contentSeo" },
+    "publishAfter": { "$ref": "#/$defs/publishAfterDate" },
     "extensions": { "$ref": "#/$defs/extensionMap" }
   },
   "additionalProperties": false,
@@ -212,6 +213,11 @@
         }
       ]
     },
+    "publishAfterDate": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "SCHEMA-3.19.0: the calendar date (`YYYY-MM-DD`, day precision, read in the publication's staggered-release timezone) on or after which Galascribe publishes this draft. Meaningful only while `status` is `draft`; Galascribe removes it when the post is published. The API enforces both rules; the schema only fixes the shape."
+    },
     "contentEdition": {
       "type": "object",
       "required": ["of", "kind", "sourceDigest", "generation", "approvedAt"],