|
6 | 6 | This is the repo for template deployment schemas hosted under `https://schema.management.azure.com/schemas`. Please see below for information on contributing and publishing updated schemas. |
7 | 7 |
|
8 | 8 | ## Updating Schemas |
| 9 | +> [!NOTE] |
9 | 10 | > We only publish template schemas for resource providers that are **publicly available**. This means that there should be no restrictions (private preview, internal-only allowlisting) on who can call your APIs. As a general rule, if there is not an API definition in the [Public API Specs Repo](https://github.com/Azure/azure-rest-api-specs), we will not consider a PR. |
10 | 11 |
|
11 | | -There are two processes for updating schemas: |
12 | | -1. **Daily autogeneration**: Schemas are automatically generated from definitions in the [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo. This requires [onboarding](/generator/README.md#onboarding-teams-to-autogeneration-pipeline) on a per-provider basis. |
13 | | -2. **Manually**: Schemas are manually authored and committed via PR. |
| 12 | +Schemas are generated and updated automatically, and should not require any action from RP teams. |
14 | 13 |
|
15 | | -### Has my team been onboarded for daily autogeneration? |
16 | | -Please see [generator/autogenlist.ts](/generator/autogenlist.ts) for the list of teams which have been onboarded. `basePath` refers to the path in the [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo, and `namespace` is the Resource Provider namespace. |
| 14 | +## Generating Locally |
| 15 | +If you want to preview or troubleshoot generation locally, you can use the generator in this repo to generate a schema from a swagger spec checked into the [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo. |
17 | 16 |
|
18 | | -**If your team has been onboarded, we do not require any manual contributions to this repo and your schemas will automatically be kept up to date by the pipeline.** |
19 | | - |
20 | | -## Authoring Schemas and submitting a PR |
21 | | -**Please ensure you have read [Updating Schemas](#updating-schemas) before continuing with this step, and only continue if this applies to your team.** |
22 | | - |
23 | | -### Authoring |
24 | | -You can use the generator in this repo to automatically generate a schema from a swagger spec checked into the [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo. |
25 | | - |
26 | | -#### Generating locally |
| 17 | +### Instructions |
27 | 18 | 1. Clone [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs). |
28 | 19 | 1. Fork this repo, and clone it locally. |
| 20 | +1. Update submodules and build dependencies: |
| 21 | + ```bash |
| 22 | + git submodule update --init --recursive |
| 23 | + npm --prefix bicep-types-az/bicep-types/src/bicep-types ci |
| 24 | + npm --prefix bicep-types-az/bicep-types/src/bicep-types run build |
| 25 | + npm --prefix bicep-types-az/src/autorest.bicep ci |
| 26 | + npm --prefix bicep-types-az/src/autorest.bicep run build |
29 | 27 | 1. Run the following commands (replace the base path accordingly - valid paths can be disovered with `npm run list-basepaths -- --specs-dir path/to/azure-rest-api-specs`): |
30 | | -```bash |
31 | | -cd generator |
32 | | -npm install |
33 | | -npm run generate-single -- --specs-dir path/to/azure-rest-api-specs --base-path myprovider/resource-manager |
34 | | -``` |
35 | | -1. Review the generator logs to ensure no errors, and review the changes generated. |
36 | | -1. Ensure that you have reviewed the guidelines under [Submitting a PR](#submitting-a-pr). |
37 | | -1. Generate a commit and push it to your fork. |
38 | | -1. Submit a pull request to this repo. Please include the full command output in a PR comment. |
39 | | - |
40 | | -Alternatively, you can hand-author your schema, but **please note** that this process is error-prone, and ARM will not be responsible for reviewing for accuracy when validating your PR. |
41 | | - |
42 | | -### Submitting a PR |
43 | | -* Ensure that any $refs to resource types that you are adding has been added to the following top-level template schema: [schemas/2019-04-01/deploymentTemplate.json](/schemas/2019-04-01/deploymentTemplate.json) |
44 | | -* If your schema has been manually generated, please ensure you include appropriate tests in [tests](/tests/) |
45 | | -* If adding a new resource type, please add examples to the templates in [tools/templateTests](/tools/templateTests/) |
46 | | -* Ensure that the test suite passes (see [Tests](#tests)) |
47 | | - |
48 | | -> **NOTE**: We will no longer be taking any updates to the [2015-01-01](/schemas/2015-01-01/deploymentTemplate.json) or [2014-04-01-preview](/schemas/2014-04-01-preview/deploymentTemplate.json) root schemas. If you are authoring a template which references one of these schemas, please upgrade it to use the [2019-04-01](/schemas/2019-04-01/deploymentTemplate.json) root schema by setting the `$schema` property to `https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"`. |
| 28 | + ```bash |
| 29 | + cd generator |
| 30 | + npm --prefix generator ci |
| 31 | + npm --prefix generator run generate-single -- --specs-dir path/to/azure-rest-api-specs --base-path myprovider/resource-manager |
| 32 | + ``` |
49 | 33 |
|
50 | 34 | ### Runing Unit Tests |
51 | 35 | Use the following commands to execute the test suite locally: |
52 | 36 | ```bash |
53 | | -cd tools |
54 | | -npm install |
55 | | -npm test |
| 37 | +npm --prefix tools ci |
| 38 | +npm --prefix tools test |
56 | 39 | ``` |
57 | 40 |
|
58 | 41 | ## Manual testing with a local schema server |
59 | 42 | This repo contains a command to run a schema web server which will host files directly from your local repo. This can be useful if you want to validate schemas against a particular tool - for example if you want to verify VSCode autocompletion and syntax highlighting. By default this will listen on port 3000, but this can be modified by editing [tools/server.ts](/tools/server.ts). |
60 | 43 | To start an instance you can use the following commands: |
61 | 44 | ```bash |
62 | | -cd tools |
63 | | -npm install |
64 | | -npm run serve |
| 45 | +npm --prefix tools ci |
| 46 | +npm --prefix tools run serve |
65 | 47 | ``` |
66 | 48 |
|
67 | 49 | Once this is running, you can create a basic template with the following structure (replacing the sections between `<` and `>` as appropriate for your scenario): |
|
0 commit comments