[native_assets_cli] Hook schemas

[dcharkes]

Bug:

• [native_assets_cli] Document the protocol #95

This PR documents the current state of JSON protocol for the hooks by means of JSON schemas.

(It is a non-goal of this PR to change the current state.)

Features of the JSON schemas

The syntax:

• Types of fields.
• Whether fields are required or optional.
• Conditionally required fields.
  • e.g. CodeConfig must have an "android" config if the "target_os" : "android".
• Format
  • e.g. That file paths must be absolute (instead of an arbitrary string).

Documentation for the evolution of schemas:

• "deprecation"s
• Comments about fallback logic for SDKs or hooks for new fields not yet fully rolled out.

Organization of the JSON schemas

• The schemas is split up in the base protocol (package:hook) and extensions (package:code_assets and package:data_assets).
  • The extension schemas extend the base schema.
  • The extension schemas should be able to be combined with allOf to get a schema with two extensions applied.
• The schemas are written in shared_definitions.schema.json files to facilitate easy re-use of subschemas occurring in multiple places (Asset, Architecture, etc.).
  • The entry points for validation are build_input.schema.json, build_output.schema.json, link_input.schema.json, and link_output.schema.json.
• Constraints and comments only relevant for hooks or only relevant for sdks are added on to the shared schema.

Testing

The schemas are tested with the help of package:json_schema. This package only supports up to meta schema 07, so this is the version we use in our schemas.

This package does not give useful error messages on validation errors, so we cannot use this for generating syntactic error messages unfortunately.

Open issues

While writing the schema, I noticed some quirks in our JSON schema:

• [native_assets_cli] Rename assetsForLinking to assets_for_linking in JSON #2037
• [native_assets_cli] Rename prefer-static to prefer_static in JSON #2038
• [native_assets_cli] input.config.code.android.target_ndk_api should be required in JSON #2039

This PR documents the current state, rather than to fix the issues in the same PR. (The first two require a breaking change and the last one requires a refactoring splitting syntactic and semantic errors.)

This PR is a step in the direction of:

• [native_assets_cli][native_assets_builder] Supporting version skew between SDK and build.dart #93

[github-actions]

PR Health

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbols

License Headers ✔️

// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/jni/lib/src/third_party/generated_bindings.dart
pkgs/objective_c/lib/src/ns_input_stream.dart

[coveralls]

coverage: 87.297% (-0.8%) from 88.062%
when pulling 053a7fb on json-schema
into 084c107 on main.

[HosseinYousefi]

It's hard to exactly review the schemas but LGTM.

[mkustermann]

First round of feedback with a few questions.