Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
This repository is the single-source-of-truth (SSOT) for all BIS schemas.
The repository is split up into two main parts; the tooling, used to process and validate the schemas, and the BIS Schemas.
All tooling will be under the "tools" directory at the root of the repository.
The BIS Domain Schemas all live under the "Domains" directory, organized by schema-layer and then domain group. Each domain group has it own directory, allowing permissions control by the domain group owner. If necessary for finer-grained permissions management, domain group owners can create further subdirectories. Otherwise, all domain schemas should be in the top-level domain group directory. There will be a "Released" subdirectory to hold domain schemas that have been publicly released.
Example:
\Domains\4-Application\{DomainGroupName}\{Domain1}.ecschema.xml
\Domains\4-Application\{DomainGroupName}\{Domain2}.ecschema.xml
\Domains\4-Application\{DomainGroupName}\Released\{Domain1.MM.mm.bb}.ecschema.xml
\Domains\4-Application\{DomainGroupName}\Released\{Domain2.MM.mm.bb}.ecschema.xml
All contributions to this repository will be done via pull requests to the master branch.
Each BIS Schema must have an owner, or owners. The owner(s) of a given BIS Schema have to approve all pull requests before they are merged into the master branch. The owner will automatically be added as a required reviewer to a pull request if it corresponds with their domain group directory (see directory structure).
All other changes made outside of a domain group directory will require review by a repository owner(s). The repository owner(s) will be added as optional reviewer(s) to all pull requests that are created within domain group directories.
NOTE: When your schema is checked into master it will automatically be published as an npm package see Schema Packaging for more information
NOTE: You will need someone from the 'BIS Release Admins' Group to approve your PR. For new schemas this generally requires some review of the schema by the BIS Working Group so coordinate with them early in the process to avoid delays and reworking when you are trying to release.
Create a branch of the bis-schemas repo to make all of your changes.
Copy the schema to the Released directory for that domain group and change the file name to include the version
\Domains\0-Core\BisCore.ecschema.xml
to \Domains\0-Core\Released\BisCore.01.00.42.ecschema.xml
Find the new entry added by the update schema inventory script it should look something like this:
{
"name": "BisCore",
"path": "Domains\\0-Core\\Released\\BisCore.01.00.42.ecschema.xml",
"released": true,
"version": "01.00.42",
"comment": "Answers the question",
"verifier": "<First.Last of the BIS Release Admin responsible for verifying this version of the schema",
"sha1": "<sha1 hash>",
"verified": "<Yes/No>", # Set to Yes when the verifier is OK with release
"author": "<First.Last of the person responsible for this version of the schema>",
"date": "<MM/DD/YYYY Date for the schemas release>",
"dynamic": "<Yes/No>", # Set to Yes if programmatically generated, else No (No is most common)
"approved": "<Yes/No>" # Set to Yes by the author when they are OK with release
},
NOTE: If a verifier is set as a required reviewer it is ok to set
verified
toYes
when you create the PR. As their approval of the PR indicates that they have verified the schema.
Update entry to fill out all fields correctly, the only optional field is 'comment'.
Run Bis Rule Validation and iModel Schema Validation on your new schema and make sure they pass.
Create a PR to merge your branch into master
Every BIS Schema within the repository has an associated owner. The owner is in charge of managing Pull Requests and permissions to the BIS Schema(s).
Permissions for an individual domain schema, or a domain group are managed through a CODEOWNERS.
The Team is owned by the schema owner, which gives them the ability to add/remove people from that team. A given team can be setup as a required reviewer for Schema(s) it owns. Anyone within that team can review/approve pull requests to the schemas. (Note: If you are within the team and you make a pull request you will still need at least one additional reviewer.)
There are set of tools exposed as npm tasks to assist schema authors in managing new or modified schemas.
To successfully run the tools described in this section, follow the steps below to setup your environment.
rush install
.Via the command line, navigate to the root of the bis-schemas repository. If you have VS Code installed, open the bis-schemas folder, and open a new Terminal (Terminal -> New Terminal in the menu, or use the shortcut (Ctrl-Shift-`).
Run the command npm install
.
The SchemaInventory.json file at the root of the bis-schemas repository contains an up-to-date inventory of all schemas in the bis-schemas repository. The schema inventory must be updated using the npm task 'updateSchemaInventory', defined in the bis-schemas package.json, for all pull-requests that define new schemas. This includes a new version of a work-in-progress schema or a new released schema.
Missing schemas will cause the
Bis Schemas - TS Validation (Github)
build to fail during pull-requests builds of the bis-schemas repository.
To run the 'updateSchemaInventory' script, follow these steps:
npm run updateSchemaInventory
approved
and verified
fields of the new schema entry in SchemaInventory.json or the validation (noted above) will fail during pull-request builds.For getting all released schemas (including all versions) jsons, use following command:
npm run generateJsonSchemas -- --allReleasedVersions --OutDir D:\\dir1\\output\\
If you just need json schemas of latest released versions:
npm run generateJsonSchemas -- --latestReleasedVersions --OutDir D:\\dir1\\output\\
BIS rule validation consists of checking all schemas in the bis-schemas repository against a set of validation rules. The npm script 'validateSchemas' uses the npm package @bentley/schema-validator
to perform the validation.
To run the 'validateSchemas' script follow these steps:
npm run validateSchemas
npm run validateSchemas -- --name SCHEMA-NAME
npm run validateSchemas -- --name BisCore
The Schema Differencing tool performs a difference audit of all schemas in the bis-schemas against their latest released version, if one exists. The npm script 'compareSchemas' uses the npm package @bentley/schema-comparer
to perform the difference audit.
To run the 'compareSchemas' script, follow these steps:
npm run compareSchemas
npm run compareSchemas -- --name SCHEMA-NAME
npm run compareSchemas -- --name BisCore
The iModel Schema Validation tool imports each individual schema in the bis-schema repository (along with schema references) into an local snapshot iModel. The schemas are then exported to a temp directory in order to perform the required validations. The following checks are performed:
@bentley/schema-validator
package.@bentley/schema-comparer
package.The npm script 'iModelSchemaValidation' uses the npm package
@bentley/imodel-schema-validator
to perform the validation.
To run the 'iModelSchemaValidation' script, follow these steps:
npm run iModelSchemaValidation
npm run iModelSchemaValidation -- --released
npm run iModelSchemaValidation -- --released SCHEMA-NAME
npm run iModelSchemaValidation -- --released BisCore
npm run iModelSchemaValidation -- --wip
npm run iModelSchemaValidation -- --wip SCHEMA-NAME
npm run iModelSchemaValidation -- --wip BisCore
npm run iModelSchemaValidation -- --multiSchema JSON-PATH
npm run iModelSchemaValidation -- --multiSchema C:\schemas.json
npm run iModelSchemaValidation -- --multiSchema
npm run iModelSchemaValidation -- --OutDir SOME-DIR
C:\Users\username\AppData\Local\Temp\SchemaValidation\Briefcases\validation
In this testing, we take latest major versions e.g 3.x.x of a schema and try to import them into an iModel to test schema upgrade from oldest to latest e.g 3.0.0 to 3.0.1 to 3.0.2.
usage: npm run iModelSchemaValidation -- --schemaUpgradeTesting --OutDir D:\dir
NOTE: Schemas listed in the ignore schema list are skipped when validating all schemas. To run validation against these schemas use a command like npm run iModelSchemaValidation -- --wip Asset
In this testing, the latest released version of Biscore and Functional schemas are imported to an iModel and then information of tables, indexes of this iModel is extracted and compared with the previously stored information for any possible changes.
usage: npm run iModelSchemaValidation -- --compareSnapshot
In case snapshots differ, use following command to generate new snapshot json:
usage: npm run iModelSchemaValidation -- --generateSnapshot
See the documentation for writing schema documentation here