mailschema 0.2.0

data/lib/mailschema/contract.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+# Type contracts an implementation vendors, verified by digest and compiled once.
+module Mailschema
+  # A type contract that fails its own checks or its pinned digest.
+  class InvalidContract < Error; end
+
+  # Reasons the core assigns to the approval lifecycle.
+  APPROVAL_REASONS = %w[declined stale-target expired superseded].freeze
+
+  # A type contract an implementation vendors, verified against the digest it was
+  # pinned by and compiled once. It checks the descriptions, requests, inputs and
+  # results of that exact type. The Registry has already applied the contract rules,
+  # such as portable patterns, to the contract that digest names; loading refuses
+  # anything that would otherwise fail at request time.
+  class Contract
+    # A MAP problem a request earns before the service's own state is consulted.
+    Problem = Data.define(:code, :title, :detail)
+
+    FIELD_VALIDATORS = 128
+    private_constant :FIELD_VALIDATORS
+
+    attr_reader :document, :digest, :request_schema
+
+    # `digest` is the contract digest the implementation pinned; `dependencies`
+    # supplies, by URL, any pinned schema the gem does not bundle.
+    def initialize(contract, request_schema, digest:, dependencies: {})
+      errors = Validation.errors(CONTRACTS, contract)
+      raise InvalidContract, "invalid type contract: #{errors.join("; ")}" if errors.any?
+      raise InvalidContract, "the contract is for another MAP profile" unless contract["profile"] == PROFILE
+
+      @document = frozen_copy(contract)
+      @digest = Mailschema.digest(@document)
+      raise InvalidContract, "the contract digest is #{@digest}, not the pinned #{digest}" unless @digest == digest
+
+      @request_schema = frozen_copy(request_schema)
+      @references = pin(@document.fetch("dependencies", []), dependencies)
+      verify_structure
+      compile
+    end
+
+    def id = document.fetch("id")
+    def version = document.fetch("version")
+
+    # The type reference a description and a request of this contract name exactly.
+    def type_reference = { "id" => id, "version" => version, "contractDigest" => digest }
+
+    def operation(id) = document.fetch("operations").find { |operation| operation.fetch("id") == id }
+
+    # Whether completing the operation decides the interaction.
+    def decision?(id)
+      found = operation(id) or raise ArgumentError, "#{id} is not an operation of this type"
+      !found.fetch("repeatable", false)
+    end
+
+    # Every rule a description must satisfy beyond the core schema, for the service
+    # that issues it and the client that receives it.
+    def description_errors(description)
+      errors = Mailschema.description_errors(description)
+      return errors if errors.any?
+      return ["The description names another type contract."] unless description.fetch("type") == type_reference
+
+      problems = details_problems(description)
+      problems.concat(operation_problems(description))
+      unless Time.iso8601(description.fetch("describedAt")) < Time.iso8601(description.fetch("expiresAt"))
+        problems << "The interaction expires before it was described."
+      end
+      problems.concat(Capability.problems(description)) if description.dig("service", "authority") == "possession"
+      problems
+    end
+
+    # The checks a service makes on a request once it has resolved the description it
+    # issued, compared the description digest and established the caller: the exact
+    # type, an offered operation the authority permits, and expiry. Nil when they
+    # pass. The service then applies its own state (a decided interaction, a stale
+    # target) and `input_errors`, in that order, before any effect.
+    def request_problem(description, request, now:)
+      unless request["type"] == type_reference && description["type"] == type_reference
+        return Problem.new("unsupported-type", "Unsupported interaction type",
+                           "The service does not implement this exact interaction type contract.")
+      end
+      unless offered?(description, request["operation"])
+        return Problem.new("unsupported-operation", "Unsupported operation",
+                           "The operation was not offered in this interaction.")
+      end
+      return unless Mailschema.reached?(now, description.fetch("expiresAt"))
+
+      Problem.new("expired-interaction", "Interaction expired",
+                  "The interaction expired before the request was processed.")
+    end
+
+    # Input problems for one request, each with a detail and a JSON Pointer into its
+    # input: the operation's input schema, then its field bindings against the
+    # description's details. Type rules a contract cannot express are the caller's.
+    def input_errors(description, request)
+      found = operation(request["operation"])
+      schema = @inputs[request["operation"]]
+      return [problem("The operation is not part of this type.", "")] unless found && schema
+
+      errors = pointer_errors(schema, request["input"])
+      return errors.first(100) if errors.any?
+
+      found.fetch("fieldBindings", [])
+           .flat_map { |binding| binding_errors(binding, description["details"], request["input"]) }
+           .first(100)
+    end
+
+    # The core result definition, then the output schema and reason this contract
+    # declares for the result's operation and state.
+    def result_errors(result)
+      errors = Mailschema.result_errors(result)
+      return errors if errors.any?
+      return ["The result names another type contract."] unless result.fetch("type") == type_reference
+
+      found = operation(result.fetch("operation"))
+      return ["#{result["operation"]} is not an operation of this type."] unless found
+
+      declared = found.fetch("results").find { |entry| entry.fetch("state") == result.fetch("state") }
+      return ["#{found["id"]} does not declare the state #{result["state"]}."] unless declared
+
+      problems = Validation.errors(@outputs.fetch([found["id"], declared["state"]]), result.fetch("output"), "/output")
+      if result["state"] == "failed" && !declared.fetch("reasons", []).include?(result["reason"])
+        problems << "#{found["id"]} does not declare the reason #{result["reason"]}."
+      end
+      problems
+    end
+
+    private
+
+    def frozen_copy(value) = deep_freeze(JSON.parse(JSON.generate(value)))
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |member| deep_freeze(member) }
+      when Array then value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+
+    def pin(dependencies, supplied)
+      references = dependencies.to_h do |dependency|
+        url = dependency.fetch("url")
+        schema = BUNDLED[url] || supplied[url]
+        raise InvalidContract, "unknown dependency #{url}" unless schema
+        unless Mailschema.digest(schema) == dependency.fetch("canonicalDigest")
+          raise InvalidContract, "the pinned digest of #{url} differs"
+        end
+
+        [url, schema.frozen? ? schema : frozen_copy(schema)]
+      end
+      raise InvalidContract, "the core schema must be pinned" unless references.key?(CORE_SCHEMA)
+
+      references.freeze
+    end
+
+    def verify_structure
+      verify_schemas
+      verify_request_schema
+      verify_operations
+      References.verify(inline_schemas, request_schema, @references, unbundled)
+    end
+
+    # The schemas the contract carries itself: its details and every output.
+    def inline_schemas
+      outputs = document.fetch("operations").flat_map do |operation|
+        operation.fetch("results").map { |result| result["outputSchema"] }
+      end
+      [document["detailsSchema"], *outputs].compact
+    end
+
+    # Every schema is valid JSON Schema 2020-12, so no malformed keyword fails when a
+    # request arrives.
+    def verify_schemas
+      [*inline_schemas, request_schema, *unbundled].each do |schema|
+        problem = Validation.invalid_schema(schema)
+        raise InvalidContract, "a schema is not valid JSON Schema 2020-12: #{problem}" if problem
+      end
+    end
+
+    def verify_request_schema
+      reference = document.fetch("requestSchema")
+      unless request_schema["$schema"] == "https://json-schema.org/draft/2020-12/schema"
+        raise InvalidContract, "the request schema must declare JSON Schema 2020-12"
+      end
+      unless request_schema["$id"] == reference["url"]
+        raise InvalidContract, "the request schema $id differs from the contract"
+      end
+      unless Mailschema.digest(request_schema) == reference["canonicalDigest"]
+        raise InvalidContract, "the request schema digest differs from the contract"
+      end
+
+      constants = SchemaWalk.values(request_schema, "const").grep(String)
+      [id, version, *operation_ids].each do |expected|
+        raise InvalidContract, "the request schema does not bind #{expected}" unless constants.include?(expected)
+      end
+    end
+
+    def verify_operations
+      raise InvalidContract, "duplicate operation identifiers" unless operation_ids.uniq == operation_ids
+
+      document.fetch("operations").each do |operation|
+        states = operation.fetch("results").map { |result| result.fetch("state") }
+        raise InvalidContract, "duplicate #{operation["id"]} result states" unless states.uniq == states
+      end
+    end
+
+    def operation_ids = document.fetch("operations").map { |operation| operation.fetch("id") }
+
+    # Every validator now, so a pattern that does not compile refuses the contract
+    # rather than a request.
+    def compile
+      references = @references.merge(request_schema.fetch("$id") => request_schema)
+      @schema = ->(value) { Validation.schema(value, references) }
+      compile_deferred
+      @details = @schema.call(document["detailsSchema"]) if document.key?("detailsSchema")
+      @inputs = branches.to_h { |operation, input| [operation, @schema.call(input)] }
+      @outputs = document.fetch("operations").flat_map do |operation|
+        operation.fetch("results").map do |result|
+          [[operation["id"], result["state"]], @schema.call(result.fetch("outputSchema"))]
+        end
+      end.to_h
+      resolve_references
+      @fields = {}
+    rescue RegexpError, JSONSchemer::InvalidEcmaRegexp => e
+      raise InvalidContract, "a pattern does not compile: #{e.message}"
+    rescue JSONSchemer::InvalidRefPointer, JSONSchemer::InvalidRefResolution, JSONSchemer::UnknownRef => e
+      raise InvalidContract, "a reference does not resolve: #{e.message}"
+    end
+
+    # The pinned schemas the gem does not bundle.
+    def unbundled = @references.reject { |url, _| BUNDLED.key?(url) }.values
+
+    # What the validator would otherwise compile at first use: pinned schemas the gem
+    # does not bundle, and the names of patternProperties.
+    def compile_deferred
+      unbundled.each { |schema| @schema.call(schema) }
+      [document, request_schema, *unbundled]
+        .flat_map { |schema| SchemaWalk.values(schema, "patternProperties").grep(Hash).flat_map(&:keys) }
+        .each { |pattern| @schema.call({ "pattern" => pattern }) }
+    end
+
+    # Every reference resolved now, into every schema it reaches, as a request would
+    # otherwise resolve it first.
+    def resolve_references = [@details, *@inputs.values, *@outputs.values].compact.each(&:bundle)
+
+    # Each operation's branch of the request schema, with its input schema.
+    def branches
+      last = request_schema.fetch("allOf", []).last || {}
+      (last["oneOf"] || [last]).to_h do |branch|
+        properties = branch["properties"] || {}
+        [properties.dig("operation", "const"), properties.fetch("input", {})]
+      end
+    end
+
+    def offered?(description, id)
+      authority = description.dig("service", "authority")
+      description.fetch("operations").any? { |offered| offered["id"] == id } &&
+        operation(id)&.fetch("authority")&.include?(authority)
+    end
+
+    def operation_problems(description)
+      ids = description.fetch("operations").map { |offered| offered.fetch("id") }
+      authority = description.dig("service", "authority")
+      problems = ids.uniq.size == ids.size ? [] : ["An operation is offered twice."]
+      ids.each do |offered|
+        unless operation(offered)&.fetch("authority")&.include?(authority)
+          problems << "#{offered} is not a #{authority} operation of this type."
+        end
+      end
+      problems
+    end
+
+    def details_problems(description)
+      details = description.key?("details") ? description["details"] : Pointer::MISSING
+      missing = details.equal?(Pointer::MISSING)
+      valid = @details ? !missing && @details.valid?(details) : missing
+      return ["The details do not satisfy the type contract."] unless valid
+
+      blocks = document.fetch("operations").flat_map do |operation|
+        operation.fetch("fieldBindings", []).map { |binding| binding["fields"] }
+      end
+      blocks.uniq.flat_map do |pointer|
+        fields = Pointer.member(details, pointer)
+        fields.equal?(Pointer::MISSING) ? [] : Forms.problems(fields).map { |found| "#{pointer}: #{found}" }
+      end
+    end
+
+    # A form-shaped input holds only the fields the details define, and satisfies them.
+    def binding_errors(binding, details, input)
+      fields = Pointer.member(details, binding.fetch("fields"))
+      values = Pointer.member(input, binding.fetch("input"))
+      if fields.equal?(Pointer::MISSING)
+        return [] if values.equal?(Pointer::MISSING)
+
+        [problem("This interaction defines no fields for these values.", binding["input"])]
+      elsif values.equal?(Pointer::MISSING)
+        return [] if fields.fetch("required", []).empty?
+
+        [problem("Values for the required fields are missing.", binding["input"])]
+      else
+        pointer_errors(fields_schema(fields), values, binding["input"])
+      end
+    end
+
+    # The compiled schema of a fields block's values. Least recently used blocks leave
+    # first, so a long-running service stays bounded.
+    def fields_schema(fields)
+      key = Mailschema.digest(fields)
+      schema = @fields.delete(key) || @schema.call(Forms.values_schema(fields))
+      @fields[key] = schema
+      @fields.shift while @fields.size > FIELD_VALIDATORS
+      schema
+    end
+
+    # Validation errors as a detail and a JSON Pointer, naming a missing member itself.
+    def pointer_errors(schema, value, prefix = "")
+      schema.validate(value).flat_map do |error|
+        at = error.fetch("data_pointer")
+        if error["type"] == "required"
+          error.dig("details", "missing_keys").map do |name|
+            problem(error["error"], "#{prefix}#{at}/#{Pointer.escape(name)}")
+          end
+        else
+          [problem(error["error"], "#{prefix}#{at}")]
+        end
+      end.uniq
+    end
+
+    def problem(detail, pointer) = Limits.input_error(detail, pointer)
+  end
+end

data/lib/mailschema/document.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Parsing MAP documents as I-JSON within the core limits.
+module Mailschema
+  class Error < StandardError; end
+
+  # A MAP document that is not I-JSON within the core limits.
+  class InvalidDocument < Error; end
+
+  MAX_BYTES = 64 * 1024
+  # Unicode's noncharacters: U+FDD0 to U+FDEF, and the last two code points of every plane.
+  NONCHARACTER = Regexp.new(
+    "[\u{FDD0}-\u{FDEF}#{(0..16).flat_map { |plane| [0xFFFE, 0xFFFF].map { (plane << 16) + _1 } }.pack("U*")}]"
+  )
+  private_constant :NONCHARACTER
+  MAX_DEPTH = 32
+  EXACT_NUMBER = (2**53) - 1
+
+  # Parse a MAP document as I-JSON (RFC 7493) within the core limits: valid UTF-8,
+  # at most 64 KiB, no duplicate member names, no lone surrogates, noncharacters or
+  # U+0000 in any string, every number within ±(2^53−1), and arrays and objects nested at most 32
+  # deep, the outermost counting as one. Comments and every other leniency RFC 8259 forbids are refused.
+  # A number with no fractional part parses as an Integer: I-JSON numbers are
+  # doubles, so 1 and 1.0 are one number, as they are to JavaScript.
+  def self.parse(json)
+    raise InvalidDocument, "a MAP document is JSON text" unless json.is_a?(String)
+
+    text = json.b.force_encoding(Encoding::UTF_8)
+    raise InvalidDocument, "the MAP document exceeds #{MAX_BYTES} bytes" if text.bytesize > MAX_BYTES
+    raise InvalidDocument, "the MAP document is not valid UTF-8" unless text.valid_encoding?
+
+    i_json(
+      JSON.parse(
+        text,
+        allow_duplicate_key: false, allow_comments: false, allow_nan: false,
+        allow_trailing_comma: false, max_nesting: MAX_DEPTH, decimal_class: BigDecimal
+      )
+    )
+  rescue JSON::ParserError => e
+    raise InvalidDocument, e.message
+  end
+
+  # The parsed value, checked for what I-JSON forbids and the parser allows. A lone
+  # surrogate escape parses into invalid UTF-8, and a number beyond the exact range
+  # parses as a Ruby Integer or decimal. Each decimal becomes the double nearest its
+  # exact value, as ECMAScript reads it; the parser's own float conversion misreads
+  # long exponents. Depth is counted here because the parser's nesting limit does not
+  # count empty arrays.
+  def self.i_json(value, depth = 0)
+    case value
+    when Hash, Array
+      raise InvalidDocument, "arrays and objects nest deeper than #{MAX_DEPTH}" if depth >= MAX_DEPTH
+
+      if value.is_a?(Hash)
+        value.to_h { |name, member| [i_json(name), i_json(member, depth + 1)] }
+      else
+        value.map { |item| i_json(item, depth + 1) }
+      end
+    when String
+      raise InvalidDocument, "the MAP document contains a lone surrogate" unless value.valid_encoding?
+      raise InvalidDocument, "the MAP document contains U+0000" if value.include?("\0")
+      raise InvalidDocument, "the MAP document contains a noncharacter" if NONCHARACTER.match?(value)
+
+      value
+    when Numeric then number(value)
+    else value
+    end
+  end
+
+  # A number as ECMAScript reads it: a decimal becomes the nearest double, and a
+  # number with no fractional part an Integer.
+  def self.number(value)
+    number = value.is_a?(BigDecimal) ? value.to_f : value
+    raise InvalidDocument, "a number is outside ±(2^53−1)" unless number.finite? && number.abs <= EXACT_NUMBER
+
+    number.to_i == number ? number.to_i : number
+  end
+  private_class_method :i_json, :number
+end

data/lib/mailschema/documents.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Building MAP results and problems, and the lifecycle rules every service applies.
+module Mailschema
+  # The HTTP status of every MAP problem code, as the core schema fixes it.
+  PROBLEM_STATUS = {
+    "invalid-request" => 400,
+    "authentication-required" => 401,
+    "refused" => 403,
+    "result-not-found" => 404,
+    "stale-target" => 409,
+    "idempotency-conflict" => 409,
+    "request-in-progress" => 409,
+    "already-decided" => 409,
+    "expired-interaction" => 410,
+    "unsupported-type" => 422,
+    "unsupported-operation" => 422
+  }.freeze
+  PROBLEM_TYPES = "https://mailschema.org/problems/"
+  NON_TERMINAL_STATES = %w[pending approval-required].freeze
+
+  # A result for a request, with every correlation member. `approval_url` is given
+  # exactly for approval-required and `reason` exactly for failed. Like every builder
+  # here, it raises ArgumentError rather than return a document the core refuses.
+  def self.result(request, state:, target:, result_url:, recorded_at:, output: {}, reason: nil, approval_url: nil,
+                  actor: nil)
+    if (state == "approval-required") == approval_url.nil?
+      raise ArgumentError, "approval_url is given exactly when the state is approval-required"
+    end
+    raise ArgumentError, "reason is given exactly when the state is failed" if (state == "failed") == reason.nil?
+
+    built({
+      "kind" => "MapResult",
+      "profile" => PROFILE,
+      "requestId" => request.fetch("requestId"),
+      "interactionId" => request.fetch("interactionId"),
+      "descriptionDigest" => request.fetch("descriptionDigest"),
+      "type" => request.fetch("type"),
+      "operation" => request.fetch("operation"),
+      "state" => state,
+      "target" => target,
+      "recordedAt" => timestamp(recorded_at),
+      "resultUrl" => result_url,
+      "actor" => actor,
+      "approvalUrl" => approval_url,
+      "reason" => reason,
+      "output" => output
+    }.compact, :result_errors)
+  end
+
+  # The next state of a pending or approval-required result. Every correlation member
+  # and the actor stay; the state, reason, output and recording time change.
+  def self.transition(result, state:, recorded_at:, reason: nil, output: {})
+    unless NON_TERMINAL_STATES.include?(result.fetch("state"))
+      raise ArgumentError, "a #{result["state"]} result is terminal"
+    end
+    raise ArgumentError, "a transition ends pending work" if NON_TERMINAL_STATES.include?(state)
+    raise ArgumentError, "reason is given exactly when the state is failed" if (state == "failed") == reason.nil?
+
+    built(result.except("approvalUrl", "reason")
+                .merge("state" => state, "reason" => reason, "output" => output, "recordedAt" => timestamp(recorded_at))
+                .compact, :result_errors)
+  end
+
+  # A problem. With `request_id` it is correlated and carries `instance`, `profile`,
+  # `requestId`, `interactionId` and `code`; without, it is plain RFC 9457. It stays
+  # within the core limits: a long detail is cut, each input error is bounded, and
+  # only as many of the first 100 errors as fit within 64 KiB are kept.
+  def self.problem(code, title:, detail:, request_id: nil, interaction_id: nil, result_url: nil, target: nil,
+                   errors: nil)
+    status = PROBLEM_STATUS.fetch(code)
+    title, detail, errors = Limits.problem_members(title, detail, errors)
+    body = { "type" => "#{PROBLEM_TYPES}#{code}", "title" => title, "status" => status, "detail" => detail }
+    raise ArgumentError, "an interaction is named only with its request" if interaction_id && !request_id
+    if request_id && code == "authentication-required"
+      raise ArgumentError, "authentication-required is never correlated"
+    end
+    if errors && !(request_id && code == "invalid-request")
+      raise ArgumentError, "errors belong to a correlated invalid-request"
+    end
+
+    body.merge!(correlation(code, request_id, interaction_id, result_url, target)) if request_id
+    built(Limits.within_document(body.merge("target" => target, "errors" => errors).compact), :problem_errors)
+  end
+
+  def self.correlation(code, request_id, interaction_id, result_url, target)
+    raise ArgumentError, "a correlated problem names its result URL" unless result_url
+    if interaction_id.nil? && code != "result-not-found"
+      raise ArgumentError, "a correlated problem names its interaction"
+    end
+    raise ArgumentError, "a stale-target problem carries the current target" if code == "stale-target" && target.nil?
+
+    { "instance" => result_url, "profile" => PROFILE, "requestId" => request_id,
+      "interactionId" => interaction_id, "code" => code }
+  end
+  private_class_method :correlation
+
+  # The HTTP status of a result: 202 while work is pending, otherwise 200.
+  def self.result_status(result) = NON_TERMINAL_STATES.include?(result.fetch("state")) ? 202 : 200
+
+  # Results stay retrievable until the later of the interaction's expiry and the
+  # retention interval measured from the latest recorded state.
+  def self.retain_until(description, recorded_at)
+    retention = description.dig("service", "execution", "resultRetentionSeconds")
+    [Time.iso8601(description.fetch("expiresAt")), recorded_at + retention].max
+  end
+
+  # An undecided approval ends as failed, with reason expired, at the interaction's
+  # expiry, whether or not anyone looks. The settled result, or nil when nothing changes.
+  def self.settle(result, description, now)
+    return unless result.fetch("state") == "approval-required" && reached?(now, description.fetch("expiresAt"))
+
+    transition(result, state: "failed", reason: "expired", recorded_at: Time.iso8601(description.fetch("expiresAt")))
+  end
+
+  def self.timestamp(time) = time.to_time.utc.iso8601(3)
+  private_class_method :timestamp
+
+  # The document, once the core definition `check` names accepts it.
+  def self.built(document, check)
+    refused = public_send(check, document)
+    raise ArgumentError, "the core refuses this document: #{refused.first(3).join("; ")}" if refused.any?
+
+    document
+  end
+  private_class_method :built
+end

data/lib/mailschema/forms.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The form fields block of forms 0.1: the rules JSON Schema cannot state, and the
+  # schema the values of a block satisfy.
+  module Forms
+    # The core definitions that give a text field's `format` its lexical form.
+    FORMATS = { "email" => "address", "uri" => "identifier", "date" => "date", "date-time" => "dateTime" }.freeze
+
+    module_function
+
+    # Every required field exists, choices are distinct, and defaults are among the
+    # choices.
+    def problems(fields)
+      properties = fields.fetch("properties", {})
+      undefined = fields.fetch("required", []).reject { |name| properties.key?(name) }
+      problems = undefined.map { |name| "required field #{name} is not defined" }
+      properties.each do |name, field|
+        choices = (field["oneOf"] || field.dig("items", "anyOf") || []).map { |choice| choice["const"] }
+        problems << "field #{name} repeats a choice" unless choices.uniq.size == choices.size
+        defaults = field.key?("default") ? Array(field["default"]) : []
+        if choices.any? && defaults.any? { |value| !choices.include?(value) }
+          problems << "field #{name} defaults to a value it does not offer"
+        end
+      end
+      problems
+    end
+
+    # The schema the values of a fields block satisfy: only its fields, each with a
+    # text field's `format` read as the core lexical form of that name.
+    def values_schema(fields)
+      properties = fields.fetch("properties", {}).transform_values do |field|
+        next field unless field.key?("format")
+
+        field.except("format").merge("$ref" => "#{CORE_SCHEMA}#/$defs/#{FORMATS.fetch(field["format"])}")
+      end
+      fields.merge("properties" => properties, "additionalProperties" => false)
+    end
+  end
+  private_constant :Forms
+end

data/lib/mailschema/http.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The HTTP binding: which requests the execution URL admits, and where results live.
+module Mailschema
+  # Whether a Content-Type admits a request rather than a 415: the media type
+  # application/json, compared case-insensitively, with no parameter other than a
+  # UTF-8 charset. Only HTTP's optional whitespace, spaces and tabs, may surround
+  # each part, and empty parameter slots are ignored, as RFC 9110 permits. Bytes that
+  # are not text admit nothing.
+  def self.json_request?(content_type)
+    text = content_type.to_s
+    return false unless text.valid_encoding?
+
+    type, *parameters = text.split(";", -1).map { |part| part.gsub(/\A[ \t]+|[ \t]+\z/, "").downcase }
+    type == "application/json" &&
+      parameters.all? { |parameter| parameter.empty? || parameter.match?(/\Acharset=(?:utf-8|"utf-8")\z/) }
+  end
+
+  # The result resource of a request: the description's template, with the request
+  # identifier encoded as ECMAScript's encodeURIComponent encodes it.
+  def self.result_url(description, request_id)
+    encoded = request_id.to_s.b.gsub(/[^A-Za-z0-9\-_.!~*'()]/n) { |byte| format("%%%02X", byte.ord) }
+    description.dig("service", "execution", "resultUrlTemplate").sub("{requestId}") { encoded }
+  end
+end