Compare assembled Smithy models for compatibility

smithy

diff

moonbit

Download zip

Author

moonrockz

Version

0.7.0

License

Apache-2.0

Repository

github.com/moonrockz/smithy

Last updated

5 hours ago

Downloads

#Model compatibility differences

Compare assembled models without filesystem or network access:

///|
pub fn compare_models(
  old_model : @smithy.Model,
  new_model : @smithy.Model,
) -> Bool {
  let result = @diff.compare(old_model, new_model)
  for event in result.events {
    println(event.id + ": " + event.message)
  }
  result.is_breaking()
}

Differences::detect exposes added and removed shapes, changed shapes with their trait changes, and metadata changes. Source locations and assembly provenance do not cause differences. Container changes include changes to their member shapes.

compare evaluates the built-in compatibility rules from the pinned Smithy reference, including member targets, constraints, nullability, defaults, entity bindings, trait breaking-change definitions and legacy diff tags. It applies the new model's suppressions and severity overrides, then preview-feature downgrades. The reference's authentication-scheme evaluator currently emits no events.

Events use the shared smithy.ValidationEvent type. events includes suppressed events and has deterministic order by event ID, shape ID, severity and message. is_breaking() is true when an event has ERROR or DANGER severity.

This test compares an old weather model with a new model. The new model adds an optional output member and removes an input member. The removed member is a breaking change:

///|
test "compare an old and a new weather model" {
  let old_model = @smithy.Loader::new()
  .add_idl(
    "old-weather.smithy",
    (
      #|$version: "2"
      #|
      #|namespace example.weather
      #|
      #|service Weather {
      #|    version: "2026-10-01"
      #|    operations: [GetForecast]
      #|}
      #|
      #|operation GetForecast {
      #|    input := {
      #|        @required
      #|        city: String
      #|
      #|        days: Integer
      #|    }
      #|
      #|    output := {
      #|        @required
      #|        summary: String
      #|
      #|        celsius: Integer
      #|    }
      #|}
    ),
  )
  .assemble().model.unwrap()
  let new_model = @smithy.Loader::new()
  .add_idl(
    "new-weather.smithy",
    (
      #|$version: "2"
      #|
      #|namespace example.weather
      #|
      #|service Weather {
      #|    version: "2026-10-01"
      #|    operations: [GetForecast]
      #|}
      #|
      #|operation GetForecast {
      #|    input := {
      #|        @required
      #|        city: String
      #|    }
      #|
      #|    output := {
      #|        @required
      #|        summary: String
      #|
      #|        celsius: Integer
      #|
      #|        humidity: Integer
      #|    }
      #|}
    ),
  )
  .assemble().model.unwrap()
  let result = @diff.compare(old_model, new_model)
  let keys = result.events.map(event => {
    let shape = event.shape.map(id => id.to_string()).unwrap_or("-")
    event.id + "|" + event.severity + "|" + shape
  })
  assert_eq(keys.length(), 2)
  assert_eq(
    keys[0],
    "AddedShape|NOTE|example.weather#GetForecastOutput$humidity",
  )
  assert_eq(keys[1], "RemovedShape|ERROR|example.weather#GetForecastInput$days")
  assert_true(result.is_breaking())
}

The constraint evaluators preserve two quirks of the pinned reference. They compare @length and @range bounds only when the trait exists in both models; adding either trait uses the generic NOTE event. Both evaluators substitute zero for an absent minimum, including @range. Introducing a nonpositive range minimum therefore produces no constraint ERROR, while removing a negative minimum can produce one. The local constraint-boundary reference cases record these behaviors. is_breaking() follows the reference's event severities.

smithy diff --old old-model.smithy --new new-model.smithy
smithy diff --old old-models/ --new new-models/ --output changes.txt

The CLI assembles each file or directory independently using local resource discovery, including JAR manifests. It prints each unsuppressed difference on one line, escaping message newlines as \n. Breaking changes or invalid models exit with status 1; invalid arguments exit with status 2. Unchanged or compatible models exit with status 0. Git and project comparison modes are not implemented.

The committed reference event manifest is generated by mise run tck:reference:diff. Regeneration requires the pinned upstream source snapshot and a JDK. --check verifies it without rewriting. Normal tests read the committed expectations and require neither Java nor network access.

ValidationEvent

source

using @moonrockz/smithy { type ValidationEvent }

A Smithy validation finding after configured severity and suppression rules.

Differences

source

pub struct Differences {
  old_model : @moonrockz/smithy.Model
Model
  new_model : @moonrockz/smithy.Model
Model
  added : Array[@moonrockz/smithy.Shape
Shape]
  removed : Array[@moonrockz/smithy.Shape
Shape]
  changed : Array[ShapeChange]
  metadata : Array[MetadataChange]
} derive(@moonbitlang/core/debug.Debug
Debug)

Semantic changes ignore source locations and assembly provenance. Container changes include changes to their first-class members.

Differences::detect

source

fn Differences::detect(old_model : @moonrockz/smithy.Model
Model, new_model : @moonrockz/smithy.Model
Model) -> Differences

MetadataChange

source

pub struct MetadataChange {
  key : String
  old_value : @moonrockz/smithy.NodeValue
NodeValue?
  new_value : @moonrockz/smithy.NodeValue
NodeValue?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Result

source

pub struct Result {
  differences : Differences
  events : Array[@moonrockz/smithy.ValidationEvent
ValidationEvent]
} derive(@moonbitlang/core/debug.Debug
Debug)

Result::is_breaking

source

fn Result::is_breaking(self : Result) -> Bool

ShapeChange

source

pub struct ShapeChange {
  old_shape : @moonrockz/smithy.Shape
Shape
  new_shape : @moonrockz/smithy.Shape
Shape
  traits : Array[TraitChange]
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

TraitChange

source

pub struct TraitChange {
  id : @moonrockz/smithy.ShapeId
ShapeId
  old_value : @moonrockz/smithy.NodeValue
NodeValue?
  new_value : @moonrockz/smithy.NodeValue
NodeValue?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A changed applied trait, including additions and removals.

compare

source

fn compare(old_model : @moonrockz/smithy.Model
Model, new_model : @moonrockz/smithy.Model
Model) -> Result

Compare two assembled models using the built-in Smithy compatibility rules. Events retain suppressions and are sorted by ID, shape, severity and message.