mailschema 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d40b5366532ded5404a82499db609a8e30e4edd70df68befef93c6c227cfb461
-  data.tar.gz: bd03b7643aa9589044fcf10fa2bf63b35b3856f370198af3663c2beb6343280d
+  metadata.gz: 34c6761c416a974a8be62a22b642f9546b62cdc4f880ebe423dc37d3dcab3260
+  data.tar.gz: ead8f3521d7b6e70a781113c530fc6d894bee5d1cda504289ead2ac94a8e9701
 SHA512:
-  metadata.gz: 8195ac0b45dfc6ee758e0c25b8e46195f4768b07ebde12debf8629377c10e97536687dcb2bf0848c94d34921803534dbb1611b3a3ace46eb6f0f850d280c0be2
-  data.tar.gz: 42b7343562247873c5c01b96a58477e0775d19274a7ce94c740c71e190bb639a5f476809446d48043f44599d8e80f855f918cf6447e229c450c6787459d081ff
+  metadata.gz: 6dee1f1ee55052fce0ea79cfe7d13c9b2446cd0ad8165f01b7979b2115fe1584262194cd00a09ef390ca709358d2c48378257e0035fb2b1c5ec8b6bc5625bc5a
+  data.tar.gz: 6f7c472a6a72a808ab8c0c493de8707ae19912935b62a55ce279231b4b918f383e1085a129b4bf073efd4bb033f6a124f683625fc9ef9654b97921daf2c3f59a

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.3.1] - 2026-10-21
+
+- `description_errors` refuses an `inLanguage` that is not a well-formed BCP 47 language tag, as MAP 0.3 Core requires.
+- Where a schema offers alternatives told apart by a constant, such as a schedule's `mode`, errors report only the alternative the value chose, or the allowed values when it chose none.
+
 ## [0.3.0] - 2026-10-07
 
 - Mail Action Protocol 0.3: strict MAP JSON parsing, RFC 8785 canonicalization and digests, descriptions, type contracts and implementation records, with the reference implementation's rules and messages.

data/README.md

@@ -47,7 +47,9 @@ All under `Mailschema`:
 - `Message.part(description)`: the `Mail::Part` that carries a description, to place in a `multipart/related` entity after the readable content.
 - `Authentication::Signature` and `Authentication.qualifying(raw_message:, signatures:, organizational_domain: nil)`: the first signature your DKIM verifier reported that qualifies the raw message, or nil. Alignment is strict unless you pass a callable that returns a domain's organizational domain.
 
-Every `*_errors` method returns an array of strings, empty when the value is valid. Schemas are validated with `json_schemer` (JSON Schema 2020-12, ECMA-262 regular expressions) against the profile artifacts the gem bundles.
+Every `*_errors` method returns an array of strings, empty when the value is valid. Schemas are validated with `json_schemer` (JSON Schema 2020-12, ECMA-262 regular expressions) against the profile artifacts the gem bundles. Where a schema offers alternatives told apart by a constant, such as a schedule's `mode`, only the alternative the value chose is reported.
+
+A check covers the document: the core rules, and that `details` and the operations are what the contract allows. Whether the service, recipient, `details` and terms match a request recorded when the person started it, whether the current time is between `issuedAt` and `expiresAt`, and whether the message is authentic are for the implementation that acts on it, under the contract's requirements and the specification.
 
 ## Links
 

data/lib/mailschema/artifacts.rb

@@ -35,14 +35,50 @@ module Mailschema
     def bundled(name) = compile(JSON.parse(File.read(File.join(ARTIFACTS, name))))
 
     # Each validation error as its JSON Pointer and message, the pointer placed inside an
-    # enclosing document by `prefix`; an error at the document's root is at /.
+    # enclosing document by `prefix`; an error at the document's root is at /. A oneOf whose
+    # branches are told apart by a const reports only the branch the value chose.
     def errors(schema, value, prefix = "")
-      schema.validate(value).map do |error|
+      chosen_branches(schema.validate(value).to_a).map do |error|
         pointer = "#{prefix}#{error.fetch("data_pointer")}"
         "#{pointer.empty? ? "/" : pointer}: #{error.fetch("error")}"
       end
     end
 
+    ONE_OF_BRANCH = %r{\A(.*/oneOf)/(\d+)(?:/|\z)}
+
+    def chosen_branches(errors)
+      errors.group_by { |error| error.fetch("schema_pointer")[ONE_OF_BRANCH, 1] }.flat_map do |one_of, group|
+        one_of ? one_of_errors(one_of, group) : group
+      end
+    end
+
+    # A failed oneOf's errors: the chosen branch's, the allowed values when the value chose none,
+    # or every branch's when no const tells them apart.
+    def one_of_errors(one_of, group)
+      branches = group.group_by { |error| error.fetch("schema_pointer")[ONE_OF_BRANCH, 2] }
+      refused = branches.transform_values { |branch| discriminator(branch, one_of) }
+      chosen = refused.select { |_, error| error.nil? }.keys
+      return branches.fetch(chosen.first) if chosen.size == 1 && refused.size > 1
+      return group unless chosen.empty?
+
+      not_one_of(refused.values) || group
+    end
+
+    def not_one_of(refusals)
+      pointers = refusals.map { |error| error.fetch("data_pointer") }.uniq
+      return unless pointers.size == 1
+
+      allowed = refusals.map { |error| error.dig("schema", "const").to_json }.join(", ")
+      [{ "data_pointer" => pointers.first, "error" => "value at `#{pointers.first}` is not one of: [#{allowed}]" }]
+    end
+
+    # The const a oneOf branch refused on a member of the value it was choosing for.
+    def discriminator(branch, one_of)
+      branch.find do |error|
+        error.fetch("type") == "const" && error.fetch("schema_pointer").sub(one_of, "").count("/") == 3
+      end
+    end
+
     CORE = bundled("core.schema.json")
     CONTRACT = bundled("contract.schema.json")
     IMPLEMENTATION = bundled("implementation.schema.json")

data/lib/mailschema/description.rb

@@ -6,9 +6,21 @@ module Mailschema
   UNSAFE = /\p{White_Space}|\p{Cc}|\p{Cf}/
   private_constant :UNSAFE
 
+  # A well-formed BCP 47 language tag: RFC 5646's langtag, privateuse and grandfathered forms.
+  LANGUAGE_TAG = Regexp.new(
+    "\\A(?:(?:[a-z]{2,3}(?:-[a-z]{3}){0,3}|[a-z]{4}|[a-z]{5,8})(?:-[a-z]{4})?(?:-(?:[a-z]{2}|[0-9]{3}))?" \
+    "(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*(?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*(?:-x(?:-[a-z0-9]{1,8})+)?" \
+    "|x(?:-[a-z0-9]{1,8})+" \
+    "|en-gb-oed|i-(?:ami|bnn|default|enochian|hak|klingon|lux|mingo|navajo|pwn|tao|tay|tsu)" \
+    "|sgn-(?:be-fr|be-nl|ch-de)|art-lojban|cel-gaulish|no-(?:bok|nyn)|zh-(?:guoyu|hakka|min|min-nan|xiang))\\z",
+    Regexp::IGNORECASE
+  )
+  private_constant :LANGUAGE_TAG
+
   # Why the value is not a MAP 0.3 description, or no reasons. Beyond the core schema: expiry
-  # follows issuance, operation identifiers are unique, and no security-sensitive identifier
-  # contains whitespace, a control or a formatting character.
+  # follows issuance, inLanguage is a well-formed BCP 47 tag, operation identifiers are unique,
+  # and no security-sensitive identifier contains whitespace, a control or a formatting
+  # character.
   def self.description_errors(value)
     errors = Schemas.errors(Schemas::CORE, value)
     return errors if errors.any?
@@ -16,6 +28,7 @@ module Mailschema
     if Time.iso8601(value["expiresAt"]) <= Time.iso8601(value["issuedAt"])
       errors << "/expiresAt: must be later than issuedAt"
     end
+    errors << "/inLanguage: must be a well-formed BCP 47 language tag" unless LANGUAGE_TAG.match?(value["inLanguage"])
     ids = value["operations"].map { |operation| operation["id"] }
     errors << "/operations: identifiers must be unique" if ids.uniq.size != ids.size
     identifiers(value).each do |pointer, identifier|

data/lib/mailschema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailschema
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailschema
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - MailSchema contributors