From 1b6e61331d22d5c38b271f0351181de53e1d64f1 Mon Sep 17 00:00:00 2001 From: behnazh-w Date: Tue, 24 Feb 2026 11:01:44 +1000 Subject: [PATCH 1/2] feat: add the JSON schema for the default Macaron buildspec Signed-off-by: behnazh-w --- .../cli_usage/command_gen_build_spec.rst | 8 ++ .../rebuild_third_party_artifacts.rst | 2 +- .../common_spec/base_spec.py | 2 +- .../schemastore/macaron_buildspec_schema.json | 130 ++++++++++++++++++ .../computer-k8s/test.yaml | 8 +- tests/integration/cases/pypi_toga/test.yaml | 8 +- tests/integration/run.py | 1 + 7 files changed, 155 insertions(+), 4 deletions(-) create mode 100644 src/macaron/resources/schemastore/macaron_buildspec_schema.json diff --git a/docs/source/pages/cli_usage/command_gen_build_spec.rst b/docs/source/pages/cli_usage/command_gen_build_spec.rst index c4112e0ab..072216339 100644 --- a/docs/source/pages/cli_usage/command_gen_build_spec.rst +++ b/docs/source/pages/cli_usage/command_gen_build_spec.rst @@ -40,3 +40,11 @@ Options .. option:: --output-format OUTPUT_FORMAT The output format. Can be `default-buildspec` (default), `rc-buildspec` (Reproducible-central build spec for Java), or `dockerfile` (currently only supported for Python packages) + +.. _gen-build-spec-schema: + +-------------------------- +Build Specification Schema +-------------------------- + +The corresponding JSON schema is available in the `resources directory `_ of the repository. Be sure to use the schema that matches your Macaron release by selecting the appropriate GitHub tag. diff --git a/docs/source/pages/tutorials/rebuild_third_party_artifacts.rst b/docs/source/pages/tutorials/rebuild_third_party_artifacts.rst index 24bb9fd22..d0ccf24a0 100644 --- a/docs/source/pages/tutorials/rebuild_third_party_artifacts.rst +++ b/docs/source/pages/tutorials/rebuild_third_party_artifacts.rst @@ -106,7 +106,7 @@ In the example above, the buildspec is located at: Step 3: Review and Use the Buildspec File ========================================= -By default we generate the buildspec in JSON format as follows: +By default we generate the buildspec in JSON format as follows (see more details about the schema :ref:`here `): .. code-block:: ini diff --git a/src/macaron/build_spec_generator/common_spec/base_spec.py b/src/macaron/build_spec_generator/common_spec/base_spec.py index 6477801fd..ac954c0a3 100644 --- a/src/macaron/build_spec_generator/common_spec/base_spec.py +++ b/src/macaron/build_spec_generator/common_spec/base_spec.py @@ -85,7 +85,7 @@ class BaseBuildSpecDict(TypedDict, total=False): has_binaries: NotRequired[bool] #: The artifacts that were analyzed in generating the build specification. - upstream_artifacts: dict[str, list[str]] + upstream_artifacts: NotRequired[dict[str, list[str]]] class BaseBuildSpec(ABC): diff --git a/src/macaron/resources/schemastore/macaron_buildspec_schema.json b/src/macaron/resources/schemastore/macaron_buildspec_schema.json new file mode 100644 index 000000000..f07921b34 --- /dev/null +++ b/src/macaron/resources/schemastore/macaron_buildspec_schema.json @@ -0,0 +1,130 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Macaron BuildSpec Schema", + "type": "object", + "description": "Schema for build specification supporting multiple languages, build tools, and metadata.", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem." + }, + "purl": { + "type": "string", + "description": "The PackageURL identifier." + }, + "language": { + "type": "string", + "description": "The programming language, e.g., 'java', 'python', 'javascript'." + }, + "build_tools": { + "type": "array", + "items": { "type": "string" }, + "description": "The build tools or package managers, e.g., 'maven', 'gradle', 'pip', etc." + }, + "macaron_version": { + "type": "string", + "description": "The version of Macaron used for generating the spec." + }, + "group_id": { + "type": ["string", "null"], + "description": "The group identifier for the project/component." + }, + "artifact_id": { + "type": "string", + "description": "The artifact identifier for the project/component." + }, + "version": { + "type": "string", + "description": "The version of the package or component." + }, + "git_repo": { + "type": "string", + "description": "The remote path or URL of the git repository." + }, + "git_tag": { + "type": "string", + "description": "The commit SHA or tag in the VCS repository." + }, + "newline": { + "type": "string", + "description": "The type of line endings used (e.g., 'lf', 'crlf')." + }, + "language_version": { + "type": "array", + "items": { "type": "string" }, + "description": "The version(s) of the programming language or runtime." + }, + "dependencies": { + "type": "array", + "items": { "type": "string" }, + "description": "List of release dependencies." + }, + "build_dependencies": { + "type": "array", + "items": { "type": "string" }, + "description": "List of build dependencies, which includes tests." + }, + "build_commands": { + "type": "array", + "items": { + "type": "array", + "items": { "type": "string" } + }, + "description": "List of shell commands to build the project." + }, + "test_commands": { + "type": "array", + "items": { + "type": "array", + "items": { "type": "string" } + }, + "description": "List of shell commands to test the project." + }, + "environment": { + "type": "object", + "additionalProperties": { "type": "string" }, + "description": "Environment variables required during build or test." + }, + "artifact_path": { + "type": ["string", "null"], + "description": "Path or location of the build artifact/output." + }, + "entry_point": { + "type": ["string", "null"], + "description": "Entry point script, class, or binary for running the project." + }, + "build_requires": { + "type": "object", + "additionalProperties": { "type": "string" }, + "description": "Required packages that must be available in the build environment." + }, + "build_backends": { + "type": "array", + "items": { "type": "string" }, + "description": "List of build back-end tools used." + }, + "has_binaries": { + "type": "boolean", + "description": "Flag to indicate if the artifact includes binaries." + }, + "upstream_artifacts": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { "type": "string" } + }, + "description": "The artifacts that were analyzed in generating the build specification." + } + }, + "required": [ + "ecosystem", + "purl", + "language", + "build_tools", + "macaron_version", + "artifact_id", + "version", + "language_version" + ], + "additionalProperties": false +} diff --git a/tests/integration/cases/org_apache_hugegraph/computer-k8s/test.yaml b/tests/integration/cases/org_apache_hugegraph/computer-k8s/test.yaml index 1a4b5f034..6cfbc8864 100644 --- a/tests/integration/cases/org_apache_hugegraph/computer-k8s/test.yaml +++ b/tests/integration/cases/org_apache_hugegraph/computer-k8s/test.yaml @@ -1,4 +1,4 @@ -# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2025 - 2026, Oracle and/or its affiliates. All rights reserved. # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/. description: | @@ -42,3 +42,9 @@ steps: kind: default_build_spec result: output/buildspec/maven/org_apache_hugegraph/computer-k8s/macaron.buildspec expected: expected_default.buildspec +- name: Validate the produced buildspec + kind: validate_schema + options: + kind: json_schema + schema: macaron_buildspec_json + result: output/buildspec/maven/org_apache_hugegraph/computer-k8s/macaron.buildspec diff --git a/tests/integration/cases/pypi_toga/test.yaml b/tests/integration/cases/pypi_toga/test.yaml index 1118f3217..2a6226ece 100644 --- a/tests/integration/cases/pypi_toga/test.yaml +++ b/tests/integration/cases/pypi_toga/test.yaml @@ -1,4 +1,4 @@ -# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2025 - 2026, Oracle and/or its affiliates. All rights reserved. # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/. description: | @@ -48,3 +48,9 @@ steps: kind: dockerfile_build_spec result: output/buildspec/pypi/toga/dockerfile.buildspec expected: expected_dockerfile.buildspec +- name: Validate the produced buildspec + kind: validate_schema + options: + kind: json_schema + schema: macaron_buildspec_json + result: output/buildspec/pypi/toga/macaron.buildspec diff --git a/tests/integration/run.py b/tests/integration/run.py index 45d7ed93a..8dc1e9cd1 100644 --- a/tests/integration/run.py +++ b/tests/integration/run.py @@ -92,6 +92,7 @@ def configure_logging(verbose: bool) -> None: DEFAULT_SCHEMAS: dict[str, Sequence[str]] = { "output_json_report": ["tests", "schema_validation", "report_schema.json"], "find_source_json_report": ["src", "macaron", "resources", "schemastore", "find_source_report_schema.json"], + "macaron_buildspec_json": ["src", "macaron", "resources", "schemastore", "macaron_buildspec_schema.json"], } From 006db30c922098e9a32d1f4597d11d39db50b069 Mon Sep 17 00:00:00 2001 From: behnazh-w Date: Tue, 24 Feb 2026 11:34:20 +1000 Subject: [PATCH 2/2] chore: move the schemas to a different dir Signed-off-by: behnazh-w --- docs/source/pages/cli_usage/command_gen_build_spec.rst | 2 +- .../{schemastore => schemas}/find_source_report_schema.json | 0 .../{schemastore => schemas}/macaron_buildspec_schema.json | 0 tests/integration/run.py | 4 ++-- tests/repo_finder/test_report_schema.py | 4 ++-- 5 files changed, 5 insertions(+), 5 deletions(-) rename src/macaron/resources/{schemastore => schemas}/find_source_report_schema.json (100%) rename src/macaron/resources/{schemastore => schemas}/macaron_buildspec_schema.json (100%) diff --git a/docs/source/pages/cli_usage/command_gen_build_spec.rst b/docs/source/pages/cli_usage/command_gen_build_spec.rst index 072216339..a310fe15d 100644 --- a/docs/source/pages/cli_usage/command_gen_build_spec.rst +++ b/docs/source/pages/cli_usage/command_gen_build_spec.rst @@ -47,4 +47,4 @@ Options Build Specification Schema -------------------------- -The corresponding JSON schema is available in the `resources directory `_ of the repository. Be sure to use the schema that matches your Macaron release by selecting the appropriate GitHub tag. +The corresponding JSON schema is available in the `resources directory `_ of the repository. Be sure to use the schema that matches your Macaron release by selecting the appropriate GitHub tag. diff --git a/src/macaron/resources/schemastore/find_source_report_schema.json b/src/macaron/resources/schemas/find_source_report_schema.json similarity index 100% rename from src/macaron/resources/schemastore/find_source_report_schema.json rename to src/macaron/resources/schemas/find_source_report_schema.json diff --git a/src/macaron/resources/schemastore/macaron_buildspec_schema.json b/src/macaron/resources/schemas/macaron_buildspec_schema.json similarity index 100% rename from src/macaron/resources/schemastore/macaron_buildspec_schema.json rename to src/macaron/resources/schemas/macaron_buildspec_schema.json diff --git a/tests/integration/run.py b/tests/integration/run.py index 8dc1e9cd1..dd79bd04a 100644 --- a/tests/integration/run.py +++ b/tests/integration/run.py @@ -91,8 +91,8 @@ def configure_logging(verbose: bool) -> None: DEFAULT_SCHEMAS: dict[str, Sequence[str]] = { "output_json_report": ["tests", "schema_validation", "report_schema.json"], - "find_source_json_report": ["src", "macaron", "resources", "schemastore", "find_source_report_schema.json"], - "macaron_buildspec_json": ["src", "macaron", "resources", "schemastore", "macaron_buildspec_schema.json"], + "find_source_json_report": ["src", "macaron", "resources", "schemas", "find_source_report_schema.json"], + "macaron_buildspec_json": ["src", "macaron", "resources", "schemas", "macaron_buildspec_schema.json"], } diff --git a/tests/repo_finder/test_report_schema.py b/tests/repo_finder/test_report_schema.py index 18bfbfa5d..f3fbbbde3 100644 --- a/tests/repo_finder/test_report_schema.py +++ b/tests/repo_finder/test_report_schema.py @@ -1,4 +1,4 @@ -# Copyright (c) 2024 - 2024, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2024 - 2026, Oracle and/or its affiliates. All rights reserved. # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/. """This module tests the report schema of the repo finder.""" @@ -17,7 +17,7 @@ def json_schema_() -> Any: """Load and return the JSON schema.""" with open( - os.path.join(MACARON_PATH, "resources", "schemastore", "find_source_report_schema.json"), encoding="utf-8" + os.path.join(MACARON_PATH, "resources", "schemas", "find_source_report_schema.json"), encoding="utf-8" ) as file: return json.load(file)