fix: reconcile RC1 API catalog contracts

Author: ayush-shah

.github/workflows/validate-examples.yml

@@ -47,6 +47,7 @@ jobs:
           git -C "${OPENMETADATA_SOURCE}" sparse-checkout init --cone
           git -C "${OPENMETADATA_SOURCE}" sparse-checkout set \
             openmetadata-service/src/main/java/org/openmetadata/service/resources \
+            openmetadata-service/src/main/java/org/openmetadata/service/security \
             openmetadata-spec/src/main/resources/json/schema
           git -C "${OPENMETADATA_SOURCE}" fetch --depth=1 origin "${OPENMETADATA_SOURCE_COMMIT}"
           git -C "${OPENMETADATA_SOURCE}" checkout --detach FETCH_HEAD

README.md

@@ -35,12 +35,15 @@ rename-service, test-suite, webhook, resource, and destructive-script demos were
 of presenting code that no longer runs against current releases. The unused OpenMetadata
 submodule, stale Snowflake workflow, and retired Python and Java SDK tutorials also remain absent.
 
-The `platform-api` catalog normalizes all 1,748 HTTP-annotated methods found in the pinned OSS
-source and maps all 112 generated `create*.py` model classes to deterministic fixtures and
-scenarios. Its 32 SDK mappings resolve to callable RC1 interfaces; the other 1,716 operations use
-explicit REST renderers. These counts are generator-derived and enforced by CI.
-
-That exhaustive inventory includes 115 hidden, 20 internal, one diagnostic, and eight test-support
+The `platform-api` catalog expands 1,748 HTTP-annotated methods found in the pinned OSS source
+into 1,985 concrete normalized operations and maps all 112 generated `create*.py` model classes
+to deterministic fixtures and scenarios. It also records 319 response models: 187 JSON Schema
+fixtures, 106 source-declared result-list envelopes, two Java scalars, and 24 shape-only fixtures
+with explicit validation boundaries. Its 32 SDK mappings have signature-checked argument bindings;
+the other 1,953 operations use explicit REST renderers. These counts are generator-derived and
+enforced by CI.
+
+That exhaustive inventory includes 133 hidden, one internal, one diagnostic, and eight test-support
 operations for source completeness. Those routes are unstable and unsupported for customer
 integrations. The catalog has no host, credential, or live-network execution mode and does not
 certify server acceptance or authorization behavior.

platform-api/README.md

@@ -19,22 +19,32 @@ Hidden, internal, diagnostic, and test-support routes are included for inventory
 completeness. They are unstable and unsupported for customer integrations. Use the public
 product documentation—not this catalog—for stable SDK learning tutorials.
 
+The pinned repository does not ship a static published OpenAPI document to compare. The
+manifest's `customer-facing` surface classification means the route has public source annotations
+and is eligible for generated OpenAPI; it does not claim independently verified publication.
+`source-only` identifies hidden, internal, diagnostic, or test-support routes. Neither label is a
+promise of API stability.
+
 ## What Is Included
 
 The generated catalog currently derives these values from the pinned source rather than
 from an approximate route scan:
 
 | Contract | RC1 coverage |
 | --- | ---: |
-| Normalized HTTP operations | 1,748 |
+| HTTP-annotated Java methods | 1,748 |
+| Concrete normalized operations | 1,985 |
 | Generated `create*.py` models | 112 |
+| Response fixtures | 319 (187 JSON Schema, 106 Java result-list, 2 scalar, 24 shape-only) |
 | Explicitly verified Python SDK mappings | 32 |
-| Deterministic REST renderers | 1,716 |
+| Deterministic REST renderers | 1,953 |
 
 - [Operation matrix](docs/generated/operations.md): verb, normalized path, Java method,
   visibility, authentication, safety, SDK or REST interface, scenarios, and source line.
 - [Asset and fixture matrix](docs/generated/assets.md): every generated create-model class,
   source schema, validation boundary, scenarios, and deterministic request body.
+- [Response fixture matrix](docs/generated/responses.md): every extracted response model,
+  fixture body, matching schema where available, and explicit shape-only boundaries.
 - [Scenario catalog](docs/generated/scenarios.md): scenario purpose, operation count,
   visibility mix, barriers, command, and expected output.
 - [Coverage summary](docs/generated/README.md): generator-derived totals and model-validation
@@ -98,8 +108,8 @@ Expected summary:
 {
   "dryRunOnly": true,
   "errorStatus": null,
-  "operations": 437,
-  "recordedRequests": 437,
+  "operations": 497,
+  "recordedRequests": 497,
   "scenario": "core-catalog-assets"
 }
 ```
@@ -118,8 +128,9 @@ Confirm that every normalized operation belongs to at least one scenario:
 .venv/bin/python -m openmetadata_demo_api coverage
 ```
 
-A complete catalog reports an empty `missingOperations` list and matching source and
-scenario operation totals.
+A complete catalog reports an empty `missingOperations` list. `sourceOperations` counts
+annotated Java methods before inheritance; `normalizedOperations` and `scenarioOperations`
+count the concrete routes after inherited methods are bound to each resource.
 
 ## Dependency Ordering
 
@@ -128,27 +139,31 @@ parents:
 
 ```mermaid
 flowchart LR
-  service["Services"] --> parent["Parent assets"]
+  service["Service creation"] --> status["Service validation and status"]
+  status --> parent["Parent assets"]
   parent --> child["Child assets"]
   child --> leaf["Leaf assets"]
   leaf --> enrichment["Lineage, profiles, sample data, usage, and status"]
   enrichment --> platform["Relationships and supporting platform records"]
-  platform --> teardown["Delete and restore lifecycle requests"]
+  platform --> teardown["Destructive lifecycle requests"]
+  teardown --> restore["Restore requests"]
 ```
 
 The planner topologically sorts every scenario, rejects missing dependencies, rejects
 cycles and duplicate step IDs, and records service requests before dependent assets.
 
 ## SDK and REST Classification
 
-An operation receives an SDK mapping only when the named interface exists and is callable
-in `openmetadata-ingestion==2.0.0.0rc1`. All other operations use an explicit REST request
-renderer. `REST only` does not mean that a route is recommended or stable; consult its
-visibility and safety columns first.
+An operation receives an SDK mapping only when the named interface exists in
+`openmetadata-ingestion==2.0.0.0rc1` and every required parameter has a deterministic binding.
+The generated call descriptor is checked against the installed method signature. All other
+operations use an explicit REST request renderer. `REST only` does not mean that a route is
+recommended or stable; consult its visibility and safety columns first.
 
 The recording boundary treats both classifications identically: neither can open a network
-connection. Success, validation failure, unauthorized, forbidden, not found, conflict, and
-unsupported-operation fixtures are deterministic where applicable.
+connection. Source-declared error responses are recorded separately from validation,
+authorization, lookup, conflict, and server-boundary simulations. The operation matrix labels
+that provenance instead of implying that every simulated response is declared by the Java API.
 
 ## Reproduce the Catalog
 
@@ -181,9 +196,12 @@ The package proves that:
 - every operation renders without unresolved path parameters or network access;
 - every operation has authentication, visibility, safety, response, and applicable error
   classifications;
+- every extracted response model has either a pinned-schema-valid fixture or an explicit
+  shape-only boundary;
 - every generated create-model has a deterministic fixture and scenario;
 - dependency graphs are acyclic and order parent records before dependent records; and
-- verified SDK mappings resolve to callable RC1 interfaces.
+- verified SDK mappings resolve to callable RC1 interfaces with complete required-argument
+  bindings.
 
 It does not prove server acceptance, authorization-policy behavior, persistence, deployment,
 or compatibility with another OpenMetadata release. After 2.0 GA, regenerate from the GA

platform-api/docs/generated/README.md

@@ -6,29 +6,36 @@
 
 - Source ref: `2.0.0-rc1-release`
 - Source commit: `8e199f486b63df9f44d4c827a9f43559d9e56e07`
-- Operations: 1748
+- HTTP-annotated Java methods: 1748
+- Concrete normalized operations: 1985
 - Generated `create*.py` models: 112
+- Response models and fixtures: 319
 - Verified SDK interfaces: 32
-- Explicit REST renderers: 1716
+- Explicit REST renderers: 1953
 
 ## Reference Pages
 
 - [Operation catalog](operations.md)
 - [Generated model and fixture catalog](assets.md)
+- [Response fixture catalog](responses.md)
 - [Dry-run scenario catalog](scenarios.md)
 
 ## Visibility
 
 | Visibility | Operations |
 | --- | ---: |
 | `diagnostic` | 1 |
-| `hidden` | 115 |
-| `internal` | 20 |
-| `public` | 1604 |
+| `hidden` | 133 |
+| `internal` | 1 |
+| `public` | 1842 |
 | `test-support` | 8 |
 
 Hidden, internal, diagnostic, and test-support routes are listed for source
 completeness. They are unsupported for customer integrations.
+The pinned source tree does not contain a static published OpenAPI document to diff.
+`customer-facing` therefore classifies public source annotations, not
+independently verified publication; `source-only` means hidden or explicitly
+classified as internal/supporting here.
 
 ## Fixture Validation
 
@@ -38,3 +45,12 @@ completeness. They are unsupported for customer integrations.
 | `json-schema-compatible+pydantic` | 4 |
 | `json-schema-only` | 4 |
 | `pydantic-only` | 3 |
+
+## Response Validation
+
+| Validation boundary | Models |
+| --- | ---: |
+| `java-result-list` | 106 |
+| `java-scalar` | 2 |
+| `json-schema` | 187 |
+| `shape-only` | 24 |