File Store Layout

The folders and file names on this page are where BimlFlex writes by default. They are a convention for people, and the name property inside each document is what identifies the entity. See Names and References in a File Store for the identity rules.

The manifest

The manifest is the file bimlflex.json at the root of the store. It is the only required file. A directory without a manifest is not a file store.

Property	Required	Holds
bimlflexFormat	Yes	The format version of the store, as major and minor version.
databaseVersion	Yes	Text.
requiredBundleVersion	No	The minimum product bundle the content requires.
customer	Yes	The customer, with the properties name and uid.
versionLine	Yes	The version line, with the properties name, policy and effectiveFromDate. The effectiveFromDate value is a date.
conventions	No	Writer preferences, with the properties defaultLayout and splitThresholdObjects. They carry no meaning for the model.

BimlFlex refuses a manifest that declares a format older than 2.0 or a major version above 2.

How an entity is carried

An entity is carried in one of four ways.

• Inline. The entity is an object inside its parent's document.
• Own file. The entity has a document of its own, such as connections/<name>.json.
• Folder with an anchor document. The entity has a folder, and an anchor document in that folder holds the entity's properties, such as connections/<name>/connection.json. Split out children of the entity are placed in collection folders inside this folder.
• Map entry. The entity is one entry of a map file that holds the entities of its kind, such as settings.json.

Entity kinds

The table lists every entity kind with its carrier and its default place in the store. A kind that has an anchor document, when it is not inline, is carried as its own file in its folder or as a folder with an anchor document.

Kind	Carrier	Folder or map file	Anchor document
Connection	Own file, or folder with an anchor document	connections	connection.json
AdfLinkedService	Own file, or folder with an anchor document	adf-linked-services	adf-linked-service.json
Batch	Own file, or folder with an anchor document	batches	batch.json
Project	Own file, or folder with an anchor document	projects	project.json
ExtensionPoint	Own file, or folder with an anchor document	extension-points	extension-point.json
BusinessEntity	Own file, or folder with an anchor document	business/entities	entity.json
BusinessModel	Own file, or folder with an anchor document	business/models	model.json
Setting	Map entry	settings.json	None
Configuration	Map entry	configurations.json	None
Macro	Map entry	macros.json	None
DataTypeMapping	Map entry	data-type-mappings.json	None
BusinessEntityType	Map entry	business/entity-types.json	None
BusinessSubject	Map entry	business/subjects.json	None
BusinessClassification	Map entry	business/classifications.json	None
BusinessDomain	Map entry	business/domains.json	None
BusinessModelConfiguration	Map entry	business/model-configurations.json	None
BusinessRelationship	Map entry	business/relationships.json	None
BusinessTag	Map entry	business/tags.json	None
LibraryRule	Map entry	library-rules.json	None
Object	Inline in its connection	objects	object.json
Column	Inline in its object	columns	column.json
BusinessAttribute	Inline in its business entity	attributes	attribute.json
BusinessModelEntity	Inline in its business model	entities	entity.json
Parameter	Inline in its connection, object or column	parameters	parameter.json
RuleSet	Inline in its object	rule-sets	rule-set.json
Rule	Inline in its rule set	rules	rule.json
RuleReference	Inline in its rule set	references	reference.json
CustomAttribute	Inline in the customAttributes property of its project, batch, connection, object or column	None (always inline)	None

For Object, Column, BusinessAttribute, BusinessModelEntity, Parameter, RuleSet, Rule and RuleReference, the name in the folder column is both the property that holds the inline members in the parent document and the default folder for split out members, such as connections/<connection>/objects/<object>/object.json. Custom attributes are always inline, in the customAttributes property of their parent. A parameter that has no parent lives in the parameters folder at the root of the store.

The JSON Schema set that the BimlFlex App serves matches each document to its kind by these paths.

Split out children

A parent document can split a collection of children out into files. The collection property in the parent document then holds a collection marker object in place of the inline members. The marker carries $files, $folder or both.

• $files lists the documents of the collection by path.
• $folder names a folder whose documents belong to the collection.

For example, "objects": { "$folder": "objects" } places the objects of a connection in the objects folder of that connection.

Each split out child also names its parent in a property of its own. See Names and References in a File Store.

Long text in a side file

A long text property, such as the biml property of an extension point, holds either the text itself or an object with $file that names a side file holding the text: { "$file": "<side file>" }.

Default values and unknown properties

A property that is absent has its default value. When BimlFlex writes a document, it leaves out properties that hold their default value.

A property the format does not know is reported as a warning (BFXF018w) and is kept when BimlFlex rewrites the file.

File names

A file store is read by name. BimlFlex never reads an entity's identity from a file name or a folder name, so you can rename a file without changing the model. When a parent lists the file in $files, update that entry to match the new file name.

The file names BimlFlex creates are derived from the entity name for readability. They are never read back as a name.

Files the format does not read

• A file or folder whose name starts with an underscore, at any depth, is scratch space. BimlFlex never reads it.
• The .bimlflex folder holds infrastructure, such as the secrets files, and is not model content.
• A recognized .json file under a kind's folder that belongs to no collection is reported as a warning (BFXF005) and is not loaded.

See File Store Diagnostic Codes for every code.