Create a data package

A data package is seed JSON the model ships: dictionaries, documents, and link tables. It is not a Meta* row. Kind: Data package.

Note

The format is exactly what Data transfer writes and reads. A new set is a new file plus an index.json row. No C# change.

How to#

1. index.json — {Model}/DataPackages/index.json, an array. Pack ids are {Model}/{id} (LocalizationSaudiArabia/vat-SA).

[
  {
    "id": "vat-SA",
    "file": "vat-SA.json",
    "caption": "Saudi VAT (ZATCA)",
    "when": "country",
    "country": "SA",
    "sort": 25
  }
]

when is once (tenant setup "Load dictionaries"), country plus an ISO2, or manual (a separate button). Country rows live in that country's localization model, not in the shared catalog: LocalizationSaudiArabia ships vat-SA and cities-SA; LocalizationUkraine ships vat-UA and cities-UA. The installer matches the legal entity's ISO2, so a Ukrainian entity never receives Saudi cities. City and Region tables still belong to Common — the pack writes into them. Tax/vat (when: "once") ships the common VAT categories and codes. LocalizationSaudiArabia/vat-SA adds the ZATCA authority, jurisdiction SA, and rates (VAT5 = 0.05 until 2020-06-30, then VAT15 = 0.15). Do not duplicate the shared categories in the country pack.

2. The package JSON — {Model}/DataPackages/<file>.json. manifest lists entities (entity, table, kind, businessKey, mode, rowCount). data holds the rows. References are $ref by business key, not by Guid:

{
  "Code": "VAT15",
  "Rate": 0.15,
  "EffectiveFrom": "2020-07-01T00:00:00Z",
  "Tax": { "$ref": "Tax", "key": { "Code": "VAT-SA" } }
}

The business key must not be a translatable Name. Otherwise a second language apply creates a second row (English Immediate next to the translated caption used as a key). Key on Code / Days / a stable pair; captions are Name plus Name_uk, Name_ru and Name_ar. Name must be isTranslatable: true, or the suffixes are ignored. rowCount must match the length of that array. Geography packs (cities-SA, cities-UA) live in the country model with when: "country" and ride the same ISO2 installer as that country's tax pack.

Link-table rows use kind: "LinkTable"; the key is the reference pair.

3. Apply it from a script — GetService<IDataPackageService>(). The script does not read the disk. ApplyAsync goes through data transfer with mode=insert: a re-run never overwrites a row the tenant already edited. A job may apply a pack. There is no platform hook after model install.

4. Bump modelVersion in the same change.

Warning

Live sync and apply-file skip the files. A data package has no kind envelope, so the warning is not a workspace envelope: …/DataPackages/vat-SA.json with created=0 updated=0 errors=[] — that looks like success. Saving the JSON does not seed the tenant. Apply through IDataPackageService.ApplyAsync (or tenant setup "Load dictionaries").

RecreateAsync wipes the pack's tables, rewinds their number sequences to StartValue, then applies. A live tenant with references will lose integrity or refuse the wipe.

What's not there yet#

Do not use that pack as a template for a catalog the tenant keeps.

Where next#