Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,6 @@ Use a tracked GitHub issue, a dedicated branch, and a pull request for every cha
The versioned Kafka contracts under `docs/contracts/` are checked by the
path-scoped `Validate AsyncAPI contracts` workflow. The dependency-free Ruby
validator checks AsyncAPI metadata, Kafka channel and operation wiring, local
references, required event/header metadata, and the declared
`BACKWARD_TRANSITIVE` Schema Registry compatibility policy. Schema Registry
deployment and credentials remain platform responsibilities.
references, required event/header metadata, representative payload examples,
and the declared `BACKWARD_TRANSITIVE` Schema Registry compatibility policy.
Schema Registry deployment and credentials remain platform responsibilities.
11 changes: 9 additions & 2 deletions docs/asyncapi-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,13 +230,20 @@ before merge. The contract check should:
topic-specific DLQ or quarantine policy.
4. Verify the `TopicNameStrategy` subject mapping, schema version, and
declared `BACKWARD_TRANSITIVE` compatibility.
5. Validate representative examples against their payload schemas and reject
credentials, tokens, secrets, and obvious customer PII.
5. Validate every representative example against its payload schema, including
required fields, constants, formats, patterns, arrays, and object
properties. The repository validator performs this deterministic local
check without requiring a schema-validation dependency.
6. Compare changed subjects with the prior contract or registry snapshot and
reject breaking changes under an existing major subject.
7. Run `git diff --check` and fail on malformed Markdown or accidental
literal escape text in documentation.

The repository gate validates the checked-in contract examples. Registry
subject comparison and live compatibility checks remain release/platform
responsibilities because pull requests must not require access to a deployed
registry or production credentials.

Pull-request validation must be deterministic and must not require access to a
deployed Kafka cluster, production registry, cloud credentials, or real
customer data. A registry integration check may run with an approved
Expand Down
96 changes: 96 additions & 0 deletions scripts/validate_asyncapi_contracts.rb
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
# Runtime Schema Registry validation remains a platform responsibility.

require "yaml"
require "time"

CONTRACT_GLOB = File.expand_path("../docs/contracts/*-asyncapi.yml", __dir__)
REQUIRED_EVENT_FIELDS = %w[
Expand Down Expand Up @@ -41,6 +42,91 @@ def expect(condition, path, message)
fail_with(path, message) unless condition
end

UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i

def normalized_pattern(pattern)
# Some YAML examples use JSON-style escaping while others use a literal
# single backslash. Normalize both forms before constructing the regexp.
pattern.gsub("\\\\", "\\")
end

def schema_matches?(document, schema, value)
schema = lookup(document, schema["$ref"], "schema validation") if schema["$ref"]

return false unless schema.fetch("allOf", []).all? { |part| schema_matches?(document, part, value) }

if schema["oneOf"]
return false unless schema["oneOf"].count { |part| schema_matches?(document, part, value) } == 1
end

if schema["anyOf"]
return false unless schema["anyOf"].any? { |part| schema_matches?(document, part, value) }
end

if schema["if"]
condition_matches = schema_matches?(document, schema["if"], value)
return false if condition_matches && schema["then"] && !schema_matches?(document, schema["then"], value)
return false if !condition_matches && schema["else"] && !schema_matches?(document, schema["else"], value)
end

return false if schema["not"] && schema_matches?(document, schema["not"], value)
return false if schema["const"] && value != schema["const"]
return false if schema["enum"] && !schema["enum"].include?(value)

case schema["type"]
when "object"
return false unless value.is_a?(Hash)
when "array"
return false unless value.is_a?(Array)
when "string"
return false unless value.is_a?(String)
when "integer"
return false unless value.is_a?(Integer)
when "number"
return false unless value.is_a?(Numeric)
when "boolean"
return false unless value == true || value == false
when "null"
return false unless value.nil?
end

return false if schema["minLength"] && (!value.is_a?(String) || value.length < schema["minLength"])
if schema["pattern"]
return false unless value.is_a?(String) && Regexp.new(normalized_pattern(schema["pattern"])).match?(value)
end
if schema["format"] == "uuid"
return false unless value.is_a?(String) && UUID_PATTERN.match?(value)
elsif schema["format"] == "date-time"
begin
Time.iso8601(value.to_s)
rescue ArgumentError
return false
end
end

if value.is_a?(Hash)
required = schema.fetch("required", [])
return false unless required.all? { |key| value.key?(key) }

properties = schema.fetch("properties", {})
if schema["additionalProperties"] == false
return false unless (value.keys - properties.keys).empty?
end
return false unless properties.all? do |key, property_schema|
!value.key?(key) || schema_matches?(document, property_schema, value[key])
end
elsif value.is_a?(Array) && schema["items"]
return false unless value.all? { |item| schema_matches?(document, schema["items"], item) }
end

true
end

def validate_example(document, schema, value, path)
expect(schema_matches?(document, schema, value), path,
"example payload does not satisfy its declared schema")
end

files = Dir[CONTRACT_GLOB].sort
expect(!files.empty?, "docs/contracts", "no AsyncAPI contracts found")

Expand Down Expand Up @@ -97,6 +183,16 @@ def expect(condition, path, message)
"payload must require all common event metadata fields")
expect(REQUIRED_HEADER_FIELDS.all? { |field| header_schema.fetch("required", []).include?(field) },
path, "headers must require all common event metadata fields")

examples = message.fetch("examples", [])
expect(examples.is_a?(Array) && !examples.empty?, path,
"at least one representative payload example is required")
examples.each_with_index do |example, index|
example_path = "#{path}.messages.#{message_name}.examples[#{index}]"
expect(example.is_a?(Hash) && example.key?("payload"), example_path,
"example payload is required")
validate_example(document, payload_schema, example["payload"], example_path)
end
end
end

Expand Down