feat: add the JSON schema for the default Macaron buildspec

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 <https://github.com/oracle/macaron/tree/main/src/macaron/resources/schemas/macaron_buildspec_schema.json>`_ of the repository. Be sure to use the schema that matches your Macaron release by selecting the appropriate GitHub tag.

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 <gen-build-spec-schema>`):
 
 .. code-block:: ini
 

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):

src/macaron/resources/schemas/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
+}

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

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

tests/integration/run.py

@@ -91,7 +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"],
+    "find_source_json_report": ["src", "macaron", "resources", "schemas", "find_source_report_schema.json"],
+    "macaron_buildspec_json": ["src", "macaron", "resources", "schemas", "macaron_buildspec_schema.json"],
 }
 
 

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)