Skip to content

Commit cfa73c1

Browse files
behnazh-wbehnazh-w
authored
feat: add the JSON schema for the default Macaron buildspec (#1314)
This PR adds a JSON schema for the buildspec output and also adds a corresponding validation step for integration tests. Signed-off-by: behnazh-w <behnaz.hassanshahi@oracle.com>
1 parent 53bda8d commit cfa73c1

9 files changed

Lines changed: 158 additions & 7 deletions

File tree

‎docs/source/pages/cli_usage/command_gen_build_spec.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,11 @@ Options
4040
.. option:: --output-format OUTPUT_FORMAT
4141

4242
The output format. Can be `default-buildspec` (default), `rc-buildspec` (Reproducible-central build spec for Java), or `dockerfile` (currently only supported for Python packages)
43+
44+
.. _gen-build-spec-schema:
45+
46+
--------------------------
47+
Build Specification Schema
48+
--------------------------
49+
50+
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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ In the example above, the buildspec is located at:
106106
Step 3: Review and Use the Buildspec File
107107
=========================================
108108

109-
By default we generate the buildspec in JSON format as follows:
109+
By default we generate the buildspec in JSON format as follows (see more details about the schema :ref:`here <gen-build-spec-schema>`):
110110

111111
.. code-block:: ini
112112

‎src/macaron/build_spec_generator/common_spec/base_spec.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ class BaseBuildSpecDict(TypedDict, total=False):
8585
has_binaries: NotRequired[bool]
8686

8787
#: The artifacts that were analyzed in generating the build specification.
88-
upstream_artifacts: dict[str, list[str]]
88+
upstream_artifacts: NotRequired[dict[str, list[str]]]
8989

9090

9191
class BaseBuildSpec(ABC):

src/macaron/resources/schemastore/find_source_report_schema.json renamed to src/macaron/resources/schemas/find_source_report_schema.json

File renamed without changes.

‎src/macaron/resources/schemas/macaron_buildspec_schema.json‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"title": "Macaron BuildSpec Schema",
4+
"type": "object",
5+
"description": "Schema for build specification supporting multiple languages, build tools, and metadata.",
6+
"properties": {
7+
"ecosystem": {
8+
"type": "string",
9+
"description": "The package ecosystem."
10+
},
11+
"purl": {
12+
"type": "string",
13+
"description": "The PackageURL identifier."
14+
},
15+
"language": {
16+
"type": "string",
17+
"description": "The programming language, e.g., 'java', 'python', 'javascript'."
18+
},
19+
"build_tools": {
20+
"type": "array",
21+
"items": { "type": "string" },
22+
"description": "The build tools or package managers, e.g., 'maven', 'gradle', 'pip', etc."
23+
},
24+
"macaron_version": {
25+
"type": "string",
26+
"description": "The version of Macaron used for generating the spec."
27+
},
28+
"group_id": {
29+
"type": ["string", "null"],
30+
"description": "The group identifier for the project/component."
31+
},
32+
"artifact_id": {
33+
"type": "string",
34+
"description": "The artifact identifier for the project/component."
35+
},
36+
"version": {
37+
"type": "string",
38+
"description": "The version of the package or component."
39+
},
40+
"git_repo": {
41+
"type": "string",
42+
"description": "The remote path or URL of the git repository."
43+
},
44+
"git_tag": {
45+
"type": "string",
46+
"description": "The commit SHA or tag in the VCS repository."
47+
},
48+
"newline": {
49+
"type": "string",
50+
"description": "The type of line endings used (e.g., 'lf', 'crlf')."
51+
},
52+
"language_version": {
53+
"type": "array",
54+
"items": { "type": "string" },
55+
"description": "The version(s) of the programming language or runtime."
56+
},
57+
"dependencies": {
58+
"type": "array",
59+
"items": { "type": "string" },
60+
"description": "List of release dependencies."
61+
},
62+
"build_dependencies": {
63+
"type": "array",
64+
"items": { "type": "string" },
65+
"description": "List of build dependencies, which includes tests."
66+
},
67+
"build_commands": {
68+
"type": "array",
69+
"items": {
70+
"type": "array",
71+
"items": { "type": "string" }
72+
},
73+
"description": "List of shell commands to build the project."
74+
},
75+
"test_commands": {
76+
"type": "array",
77+
"items": {
78+
"type": "array",
79+
"items": { "type": "string" }
80+
},
81+
"description": "List of shell commands to test the project."
82+
},
83+
"environment": {
84+
"type": "object",
85+
"additionalProperties": { "type": "string" },
86+
"description": "Environment variables required during build or test."
87+
},
88+
"artifact_path": {
89+
"type": ["string", "null"],
90+
"description": "Path or location of the build artifact/output."
91+
},
92+
"entry_point": {
93+
"type": ["string", "null"],
94+
"description": "Entry point script, class, or binary for running the project."
95+
},
96+
"build_requires": {
97+
"type": "object",
98+
"additionalProperties": { "type": "string" },
99+
"description": "Required packages that must be available in the build environment."
100+
},
101+
"build_backends": {
102+
"type": "array",
103+
"items": { "type": "string" },
104+
"description": "List of build back-end tools used."
105+
},
106+
"has_binaries": {
107+
"type": "boolean",
108+
"description": "Flag to indicate if the artifact includes binaries."
109+
},
110+
"upstream_artifacts": {
111+
"type": "object",
112+
"additionalProperties": {
113+
"type": "array",
114+
"items": { "type": "string" }
115+
},
116+
"description": "The artifacts that were analyzed in generating the build specification."
117+
}
118+
},
119+
"required": [
120+
"ecosystem",
121+
"purl",
122+
"language",
123+
"build_tools",
124+
"macaron_version",
125+
"artifact_id",
126+
"version",
127+
"language_version"
128+
],
129+
"additionalProperties": false
130+
}

‎tests/integration/cases/org_apache_hugegraph/computer-k8s/test.yaml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
1+
# Copyright (c) 2025 - 2026, Oracle and/or its affiliates. All rights reserved.
22
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
33

44
description: |
@@ -42,3 +42,9 @@ steps:
4242
kind: default_build_spec
4343
result: output/buildspec/maven/org_apache_hugegraph/computer-k8s/macaron.buildspec
4444
expected: expected_default.buildspec
45+
- name: Validate the produced buildspec
46+
kind: validate_schema
47+
options:
48+
kind: json_schema
49+
schema: macaron_buildspec_json
50+
result: output/buildspec/maven/org_apache_hugegraph/computer-k8s/macaron.buildspec

‎tests/integration/cases/pypi_toga/test.yaml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
1+
# Copyright (c) 2025 - 2026, Oracle and/or its affiliates. All rights reserved.
22
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
33

44
description: |
@@ -48,3 +48,9 @@ steps:
4848
kind: dockerfile_build_spec
4949
result: output/buildspec/pypi/toga/dockerfile.buildspec
5050
expected: expected_dockerfile.buildspec
51+
- name: Validate the produced buildspec
52+
kind: validate_schema
53+
options:
54+
kind: json_schema
55+
schema: macaron_buildspec_json
56+
result: output/buildspec/pypi/toga/macaron.buildspec

‎tests/integration/run.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,8 @@ def configure_logging(verbose: bool) -> None:
9191

9292
DEFAULT_SCHEMAS: dict[str, Sequence[str]] = {
9393
"output_json_report": ["tests", "schema_validation", "report_schema.json"],
94-
"find_source_json_report": ["src", "macaron", "resources", "schemastore", "find_source_report_schema.json"],
94+
"find_source_json_report": ["src", "macaron", "resources", "schemas", "find_source_report_schema.json"],
95+
"macaron_buildspec_json": ["src", "macaron", "resources", "schemas", "macaron_buildspec_schema.json"],
9596
}
9697

9798

‎tests/repo_finder/test_report_schema.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Copyright (c) 2024 - 2024, Oracle and/or its affiliates. All rights reserved.
1+
# Copyright (c) 2024 - 2026, Oracle and/or its affiliates. All rights reserved.
22
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
33

44
"""This module tests the report schema of the repo finder."""
@@ -17,7 +17,7 @@
1717
def json_schema_() -> Any:
1818
"""Load and return the JSON schema."""
1919
with open(
20-
os.path.join(MACARON_PATH, "resources", "schemastore", "find_source_report_schema.json"), encoding="utf-8"
20+
os.path.join(MACARON_PATH, "resources", "schemas", "find_source_report_schema.json"), encoding="utf-8"
2121
) as file:
2222
return json.load(file)
2323

0 commit comments

Comments
 (0)