Add first draft of iModelsForDevelopers.md#8878
Conversation
|
@iTwin/itwinjs-core-ec, @diegoalexdiaz , @grigasp , @pmconne, @wgoehrig , @ben-polinsky can you guys take a pass? I know this wasn't originally intended for review yet, but due to recent changes I'd like to make sure this doesn't get lost |
Co-authored-by: Ben Polinsky <78756012+ben-polinsky@users.noreply.github.com>
Co-authored-by: Ben Polinsky <78756012+ben-polinsky@users.noreply.github.com>
Co-authored-by: Ben Polinsky <78756012+ben-polinsky@users.noreply.github.com>
Co-authored-by: Ben Polinsky <78756012+ben-polinsky@users.noreply.github.com>
Co-authored-by: Ben Polinsky <78756012+ben-polinsky@users.noreply.github.com>
Co-authored-by: Ben Polinsky <78756012+ben-polinsky@users.noreply.github.com>
|
|
||
| ### BIS Basics | ||
|
|
||
| Base Infrastructure Schemas (BIS) is an open source set of schemas ([GitHub Repo](https://github.com/itwin/bis-schemas)). The [BisCore](https://www.itwinjs.org/bis/domains/biscore.ecschema/) schema defines the iModel file format, and all other schemas derive from the base classes BisCore defines. BisCore defines [**Elements**](https://www.itwinjs.org/bis/guide/fundamentals/element-fundamentals/) which store all data and [**Models**](https://www.itwinjs.org/bis/guide/fundamentals/model-fundamentals/) which contain all Elements. Elements may also be extended via [**ElementAspects**](https://www.itwinjs.org/bis/guide/fundamentals/elementaspect-fundamentals/) which are considered conceptually to be part of the Element. Individual Elements are connected via [**Relationships**](https://www.itwinjs.org/bis/guide/fundamentals/relationship-fundamentals/) to build assemblies, systems, networks, hierarchies or other arbitrary connections. |
There was a problem hiding this comment.
I propose:
Base Infrastructure Schemas (BIS) is an open source ecosystem of modular and coordinated schemas...
aruniverse
left a comment
aruniverse
left a comment
There was a problem hiding this comment.
Ran a thorough technical + structural review pass. There are a few factual issues that need fixing before this lands, plus some structural/clarity suggestions. Inline comments on each specific spot below; summary up top.
Blockers
- Wrong NAPI link (line 47) — points to
iModelPlatform(C++ business logic), notiModelJsNodeAddon(the actual N-API binding layer) - "Locks are optional" (line 33) — misleading; in the default pessimistic policy locks are required, not optional
- "rebased" (line 35) — iTwin.js docs use "merged" everywhere; "rebase" carries Git history-rewriting semantics that don't apply here
- Orphan page —
docs/learning/leftNav.mdhas no entry for this file; it will be unreachable from site nav after merge
High
- "Elements store all data" (line 41) — too broad; ElementAspects and Relationships also store data
- "BisCore defines the iModel file format" (line 41) — imprecise; BisCore defines the data model, not the physical file format (that's ECDb/BeSQLite)
- Missing ECSQL link (line 20) — ECSQL is introduced by name with no link;
./ECSQL.mdexists - SnapshotDb not mentioned (line 31) — "edit as a standalone SQLite file" describes
SnapshotDbbut never names it
Medium
- Section ordering (line 39) — BIS Basics comes after Editing, but Editing already says "BIS Element level" before BIS has been explained
- "Beyond the file" heading (line 23) — opaque; consider "Change History and Versioning"
- Weak opener (line 3) — "This document is an attempt to give a quick overview" hedges unnecessarily
- All content under one
## Overview— 7 subsections under a single H2 collapses nav; key sections (The File, Editing, BIS Basics, Code Basics) would benefit from being H2
| @@ -0,0 +1,48 @@ | |||
| # iModels for Developers | |||
|
|
|||
| This document is an attempt to give a quick overview of iModels from a developer perspective and to provide links to more detailed documentation and actual code. | |||
There was a problem hiding this comment.
Weak opener. "This document is an attempt to give a quick overview" hedges the reader's confidence in the content. Suggest:
This page gives a developer-oriented overview of iModels — what they are, how they are structured, and how iTwin.js exposes them.
|
|
||
| ### The Tables | ||
|
|
||
| While iModels physically store data using a SQL persistence schema, they expose that data as BIS entities. The ECSQL language allows you to use SQL syntax to query data in an iModel based on its conceptual schema rather than in terms of the underlying database structure. The data tables in an iModel are defined by the imported BIS schemas. Additionally, the database includes metadata tables that store these schemas and define how the persistence layer maps to the logical layer. |
There was a problem hiding this comment.
Missing ECSQL link. ECSQL is introduced here by name but with no link. docs/learning/ECSQL.md and docs/learning/ECSQLTutorial/ both exist and are already in leftNav.md.
The [ECSQL](./ECSQL.md) language allows you to use SQL syntax...| While iModels physically store data using a SQL persistence schema, they expose that data as BIS entities. The ECSQL language allows you to use SQL syntax to query data in an iModel based on its conceptual schema rather than in terms of the underlying database structure. The data tables in an iModel are defined by the imported BIS schemas. Additionally, the database includes metadata tables that store these schemas and define how the persistence layer maps to the logical layer. | ||
|
|
||
|
|
||
| ### Beyond the file |
There was a problem hiding this comment.
Opaque heading. A developer scanning section headers won't know this covers change history and versioning. Consider: ### Change History and Versioning
|
|
||
| ### Editing | ||
|
|
||
| It is possible to edit an iModel as a standalone SQLite file and produce no change history. To produce a change history, the iModel must be managed by the iModel Hub [using the iModel APIs mentioned above](https://developer.bentley.com/apis/imodels-v2/overview/). When managed by the Hub, the user is able to checkout a [**Briefcase**](https://developer.bentley.com/apis/imodels-v2/operations/acquire-imodel-briefcase/) and use [**Locks**](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-locks/) on elements to avoid data conflicts. |
There was a problem hiding this comment.
SnapshotDb not named. "Edit as a standalone SQLite file" describes SnapshotDb, but a developer looking at the API won't find it by that description. Worth naming it here and linking to AccessingIModels.md:
To edit an iModel locally without producing a change history, use a SnapshotDb — a static SQLite file not connected to iModelHub.
|
|
||
| It is possible to edit an iModel as a standalone SQLite file and produce no change history. To produce a change history, the iModel must be managed by the iModel Hub [using the iModel APIs mentioned above](https://developer.bentley.com/apis/imodels-v2/overview/). When managed by the Hub, the user is able to checkout a [**Briefcase**](https://developer.bentley.com/apis/imodels-v2/operations/acquire-imodel-briefcase/) and use [**Locks**](https://developer.bentley.com/apis/imodels-v2/operations/get-imodel-locks/) on elements to avoid data conflicts. | ||
|
|
||
| These locks are optional, and enable conflict-free editing by restricting who can modify an Element and its children. Briefcases ensure Element ids are unique by appending a briefcase id to the sequential id specified for the next element. |
There was a problem hiding this comment.
"Locks are optional" is misleading. Under the default pessimistic concurrency policy, locks are required before modifying elements — skipping them raises an error. "Optional" only applies at iModel creation time (you opt into optimistic policy via noLocks: true).
Suggested replacement:
Under the default pessimistic concurrency policy, locks are required before modifying an element. An iModel can instead be created with an optimistic policy (
noLocks: true) that allows editing without locks and reconciles changes through merge conflict-resolution. See Concurrency Control.
Ref: docs/learning/backend/ConcurrencyControl.md — "If noLocks is not specified (the default), iTwin.js will enforce that the appropriate locks must be acquired before modifying elements."
|
|
||
| These locks are optional, and enable conflict-free editing by restricting who can modify an Element and its children. Briefcases ensure Element ids are unique by appending a briefcase id to the sequential id specified for the next element. | ||
|
|
||
| As multiple users edit an iModel, they will push changesets with their changes and pull in changesets with others' changes. A briefcase must be at the tip of the change history to push a changeset. If it is not, incoming changesets need to be pulled, and local changes are rebased on top of them. Once conflicts are resolved, the local changes are pushed as one or more changesets. |
There was a problem hiding this comment.
Wrong terminology: "rebased" → "merged". iTwin.js docs use "merge" everywhere for this operation (Glossary.md, iModelHub/index.md, ConcurrencyControl.md). "Rebase" implies Git-style history rewriting, which is not what happens — incoming changesets are applied and conflicts are resolved, i.e. a merge.
local changes are **merged** with them|
|
||
| Forks create an independent copy of the change history, creating an iModel which can be edited independently from the source iModel. Changes must be merged back using [iModel Transformation](https://www.itwinjs.org/learning/transformer/) which works at the BIS Element level rather than with SQLite changesets. | ||
|
|
||
| ### BIS Basics |
There was a problem hiding this comment.
Section ordering issue. BIS Basics appears after the Editing section, but line 37 (Forks) already references "the BIS Element level" before BIS has been introduced. A developer reading top-to-bottom encounters unexplained jargon.
Suggested order: The Data → The File → The Tables → BIS Basics → Beyond the File/Change History → Editing → Code Basics
|
|
||
| ### BIS Basics | ||
|
|
||
| [Base Infrastructure Schemas](https://github.com/itwin/bis-schemas) (BIS) is an open source ecosystem of modular and coordinated schemas. The [BisCore](https://www.itwinjs.org/bis/domains/biscore.ecschema/) schema defines the iModel file format, and all other schemas derive from the base classes BisCore defines. BisCore defines [**Elements**](https://www.itwinjs.org/bis/guide/fundamentals/element-fundamentals/) which store all data and [**Models**](https://www.itwinjs.org/bis/guide/fundamentals/model-fundamentals/) which contain all Elements. Elements may also be extended via [**ElementAspects**](https://www.itwinjs.org/bis/guide/fundamentals/elementaspect-fundamentals/) which are considered conceptually to be part of the Element. Individual Elements are connected via [**Relationships**](https://www.itwinjs.org/bis/guide/fundamentals/relationship-fundamentals/) to build assemblies, systems, networks, hierarchies or other arbitrary connections. |
There was a problem hiding this comment.
Two precision issues in this sentence:
-
"defines the iModel file format" — imprecise. The physical file format (SQLite structure, changeset binary layout) is defined by ECDb and BeSQLite. BisCore defines the data model.
→The BisCore schema defines the foundational data model of an iModel -
"Elements which store all data" — too broad. ElementAspects and Relationships also store data (the sentence three lines later even says so).
iModels.mddescribes Elements as "the smallest independently addressable building block" without claiming they store all data.
→Elements as the primary data-carrying entities
|
|
||
| ### Code Basics | ||
|
|
||
| The [ECDb](https://github.com/iTwin/imodel-native/tree/main/iModelCore/ECDb) library underpins the iModel file format and uses [ECSchemas](https://www.itwinjs.org/bis/ec/) as its data modeling language. ECSchemas can be represented in [XML](https://github.com/iTwin/bis-schemas/blob/master/System/xsd/ECSchemaXML3.2.xsd) or [JSON](https://github.com/iTwin/bis-schemas/blob/master/System/json_schema/ec32/ecschema.schema.json) and loaded using TypeScript ([ecschema-metadata](https://github.com/iTwin/itwinjs-core/tree/master/core/ecschema-metadata)) or C++ ([ECObjects](https://github.com/iTwin/imodel-native/tree/main/iModelCore/ecobjects)) libraries. The C++ [iModelPlatform](https://github.com/iTwin/imodel-native/tree/main/iModelCore/iModelPlatform) layer adds basic logic that understands and enforces BisCore concepts. This internal API is exposed to TypeScript via a [NAPI interface](https://github.com/iTwin/imodel-native/tree/main/iModelCore/iModelPlatform) consumed by the iTwin.js [core-backend](https://github.com/iTwin/itwinjs-core/tree/master/core/backend) package. |
There was a problem hiding this comment.
Wrong NAPI link — blocker. Both occurrences of iModelCore/iModelPlatform in this sentence point to the C++ BIS business logic layer (Elements, Models, TxnManager). The actual N-API binding layer (the code that bridges C++ to Node.js) is iModelJsNodeAddon/:
This internal API is exposed to TypeScript via a [N-API interface](https://github.com/iTwin/imodel-native/tree/main/iModelJsNodeAddon) consumed by the iTwin.js [core-backend](https://github.com/iTwin/itwinjs-core/tree/master/core/backend) package.The first link ([iModelPlatform]) on this line is correct — that is the iModelPlatform layer. Only the second [NAPI interface] link needs to change.
Also worth adding a closing sentence pointing developers to the TypeScript entry points they'd actually use:
In TypeScript,
BriefcaseDbandSnapshotDb(from@itwin/core-backend) are the primary entry points for working with iModels.
8 participants
Rough draft for review by team to identify what else we should add and how to organize this as we add more ... doc not ready for review to merge