Skip to content

JSON Validation to fluent builder pattern#1194

Open
timkimadobe wants to merge 30 commits into
adobe:dev-v5.7.1from
timkimadobe:json-comparison
Open

JSON Validation to fluent builder pattern#1194
timkimadobe wants to merge 30 commits into
adobe:dev-v5.7.1from
timkimadobe:json-comparison

Conversation

@timkimadobe

@timkimadobe timkimadobe commented Dec 17, 2025

Copy link
Copy Markdown
Contributor

Description

This PR:

  1. Updates CircleCI config to
    1. Specify the resource class (m4pro.medium)
    2. Update iOS and tvOS sim OS from 17.5 -> 18.5
    3. Update iOS sim from iPhone 15 -> 16
  2. Updates Makefile default device from iPhone 15 -> 16
  3. Fixes test case in AEPCore/Tests/FunctionalTests/Configuration/ConfigurationAppIDTests.swift
    1. line: XCTAssertEqual(mockRuntime.firstSharedState?.toAnyCodable(), mockRuntime.secondSharedState?.toAnyCodable()) to use JSON validation instead
  4. Adds AGENTS.md to the Core repo
    1. Top level AGENTS.md to give agents context on how to navigate the modules, including directing them to the JSON validation documentation when constructing/migrating tests
    2. JSON validation level AGENTS.md which gives context on how to add/modify the logic and everything that needs to be updated
  5. Updates the JSON validation APIs to use a fluent builder pattern instead of the current parameterized path options approach.
    1. Embraces test-only utility status and removes the extra protocol conformance to add JSON validation APIs (AnyCodableAsserts)
    2. Splits out functionality into separate files where responsibilities are different enough

Before

assertExactMatch(expected: e, actual: a, pathOptions: [
    AnyOrderMatch(paths: "events"),
    ValueTypeMatch(paths: "events[*].timestamp"),
    KeyMustBeAbsent(paths: "events[*].legacy_id")
])

After

assertJSON(expected: e, actual: a)
    .anyOrder(at: "events[*]")
    .typeMatch(at: "events[*].timestamp")
    .keyMustBeAbsent(at: "events[*].legacy_id")
    .validate()

It consolidates the assertion API into a single entry point with the following default validation configurations:

  1. Exact Value Matching - Values must match exactly (type and literal value).
  2. Strict Array Ordering - Array elements must match in the given order.
  3. Extensible Collections -actual can contain more keys/elements than expected (subset match).

Important

This is a breaking change for the older JSON validation APIs, since the MultiPathConfig used to configure options has been replaced with the new JSONPath and builder APIs.
However, migration instructions have been included in the new doc: Documentation/Testing/JSONValidation.md (useful for devs and agents)

It also includes:

  • Fix for a bug where a comparison option wasn't implemented (ValueNotEqual)
  • Unit test cases for all components of the JSON validation logic

Additional context

Old MultiPathConfig New Builder Method
AnyOrderMatch .anyOrder(at: ...)
CollectionEqualCount .equalCount(at: ...)
ElementCount .elementCount(count, at: ...)
KeyMustBeAbsent .keyMustBeAbsent(at: ...)
ValueNotEqual .valueNotEqual(at: ...)
ValueExactMatch .exactMatch(at: ...)
ValueTypeMatch .typeMatch(at: ...)

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • I have signed the Adobe Open Source CLA.
  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

@timkimadobe timkimadobe requested a review from praveek December 17, 2025 02:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant