Workspace configuration (`datapackage.json` extension)
Workspace configuration (datapackage.json extension)
Each BusDK workspace directory represents exactly one accounting entity. All datasets under that workspace belong to that entity by construction, so scope separation is enforced by filesystem boundaries rather than by repeating an “entity key” on every row.
Entity-wide settings are stored as BusDK metadata in the workspace’s Frictionless Data Package descriptor (datapackage.json) at the workspace root. To create an empty descriptor, use bus data init. To create or update the descriptor and accounting entity settings in one step, use the bus config CLI. Modules read these settings when they validate, post, reconcile, report, or produce filings, and they must not require row-level datasets to repeat them.
The accounting settings live under the top-level busdk.accounting_entity object in datapackage.json. Optional workspace storage defaults for modules that support fixed-block padded CSV live under top-level _pcsv. Optional module-specific storage overrides live under busdk.storage.modules.<module>. This uses Frictionless descriptor extensibility — additional properties remain compatible with standard tooling, and tooling that does not understand BusDK can safely ignore the busdk object.
Location
datapackage.json lives at the workspace root:
{
"_pcsv": {
"version": "PCSV-1",
"paddingField": "_pad",
"recordBytes": 256,
"paddingChar": " "
},
"profile": "tabular-data-package",
"resources": [],
"busdk": {
"storage": {
"modules": {
"bus-journal": {
"version": "csv"
}
}
},
"accounting_entity": {
"business_name": "Example Oy",
"business_id": "1234567-1",
"entity_kind": "business",
"business_form": "oy",
"base_currency": "EUR",
"fiscal_year_start": "2026-01-01",
"fiscal_year_end": "2026-12-31",
"vat_registered": true,
"vat_reporting_period": "quarterly",
"vat_timing": "performance",
"vat_default_source": "invoice",
"vat_default_basis": "accrual",
"vat_registration_start": null,
"vat_registration_end": null,
"id_generation": {
"types": {
"voucher_id": {
"strategy": "sequence",
"template": "V-{yyyy}-{inc}"
}
}
},
"reporting_profile": {
"fi_statutory": {
"reporting_standard": "fi-kpa",
"language": "fi",
"income_statement_scheme": "by_nature",
"comparatives": true,
"presentation_currency": "EUR",
"presentation_unit": "EUR",
"prepared_under_pma": false,
"signature": {
"signers": [
{ "name": "Hallitus / Board", "role": "board" }
],
"date": null
}
}
}
}
}
}
Keys
base_currency is the workspace’s base currency for reporting and review. It should be an ISO 4217 code such as EUR or SEK.
business_name is the legal/business name used for workspace-level reporting and filing metadata. business_id is the legal identifier of that entity, such as Finnish Y-tunnus (NNNNNNN-N). business_form is the business form profile for the entity, such as tmi/toiminimi, oy, ky, ay, ry, osk, or sr.
entity_kind is the workspace-level classification key for downstream defaults. Supported values are business and personal. business is the default, and older workspaces that do not yet store the key are treated as business for compatibility. The key belongs under busdk.accounting_entity because it is workspace identity metadata, not a row-level fact.
fiscal_year_start and fiscal_year_end define the fiscal year boundaries for the workspace. They are dates in YYYY-MM-DD form and must form a coherent year boundary for period generation, validation, and year-end workflows.
vat_registered indicates whether the workspace’s accounting entity is VAT registered. It is the primary switch that determines whether VAT reporting expectations apply.
vat_reporting_period defines the current (or default) VAT reporting cadence. Allowed values: monthly, quarterly, yearly. Under Finnish rules, monthly is the default; quarterly is allowed when turnover is below the applicable threshold (100 000 EUR); yearly is allowed when turnover is below the lower threshold (30 000 EUR). Primary producers and visual artists who do not run other VAT-taxable business typically use a yearly period. See Vero: Arvonlisäveron verokausi ja sen muutokset. The actual sequence of period boundaries (including changes within a year, transition periods, or non-standard first/last periods) is defined by the bus-vat module, not in this descriptor.
vat_timing selects which date determines VAT period allocation. Allowed values: performance (suoriteperuste — allocation by delivery or performance date), invoice (laskutusperuste — allocation by the period in which the customer is charged), cash (maksuperuste — allocation by payment date for sales and purchases). Cash basis applies only to domestic supplies; under Finnish rules it is available only when annual turnover does not exceed the eligibility threshold (500 000 EUR), and VAT must be reported no later than 12 months after delivery or performance even if unpaid. When switching from cash to performance or invoice basis, previously unpaid sales are reported in the next open VAT period. See Vero: Pienet yritykset voivat tilittää arvonlisäveron maksuperusteisesti.
vat_default_source and vat_default_basis define default execution mode for VAT commands when --source and --basis are omitted. Allowed source values are invoice, journal, and reconcile. Allowed basis values are accrual and cash. The cash basis default requires source journal or reconcile.
vat_registration_start (optional) is the date from which the entity is VAT registered, in YYYY-MM-DD form. vat_registration_end (optional) is the date on which VAT registration ends. The bus-vat module uses these as inputs when it builds the sequence of VAT periods (including partial first or last periods and any non-standard period lengths). Omit or set to null when not applicable. See Vero: Arvonlisäveron verokausi ja sen muutokset.
id_generation is optional shared BusDK configuration for primary-key and visible numbering rules. It is intended for cross-module ID policy such as voucher numbering, invoice numbering, and immutable technical ID defaults. The structure is owned by bus-config and consumed by modules that generate durable IDs. Inline JSON and @file values can be written with bus config set --id-generation ... or bus config set id-generation ....
_pcsv is optional workspace-level storage policy metadata for modules that support PCSV-1. version selects the storage format (PCSV-1); paddingField names the fixed-width padding column, recordBytes defines the on-disk row size, and paddingChar defines the padding byte. Omit _pcsv or run bus config set storage-format csv to keep ordinary CSV as the workspace default.
busdk.storage.modules.<module> is optional per-module storage policy metadata. It uses the same fields as _pcsv, but only for one module. bus-data resolves storage policy in this order: module defaults from code, workspace _pcsv, busdk.storage.modules.<module>, and finally resource-level _pcsv. That means CSV remains the default unless one of those layers explicitly selects PCSV-1.
reporting_profile.fi_statutory defines deterministic presentation settings for Finnish statutory financial statements in bus-reports. These are presentation controls, not posting business logic, and they must remain committed and auditable in workspace data.
This reporting profile is the workspace entity-context layer, not the place for per-account classification or company-specific statement-line exceptions. The background model is described in Finnish reporting taxonomy and account classification: statutory taxonomy, account meaning, entity context, and overrides should stay separate even when they all affect the final statement output.
reporting_profile.fi_statutory.reporting_standard selects the statutory framework family (fi-kpa or fi-pma) used as the default for built-in statement layouts.
reporting_profile.fi_statutory.language selects statement labels. Current value is fi; sv is reserved for later support.
reporting_profile.fi_statutory.income_statement_scheme selects income statement structure (by_nature for kululajikohtainen, by_function for toimintokohtainen). This controls default layout selection and validation expectations.
reporting_profile.fi_statutory.comparatives controls whether comparative columns are included by default when prior-period data is available. Default is true. First fiscal year is the normal exception because no prior period exists.
Comparative figures are derived only from the current workspace. In
bus-reports, balance-sheet, profit-and-loss,
evidence-pack, and annual-validate first use prior-year journal rows that
already exist in the workspace. For full-year annual statements, if those rows
are absent, bus-reports falls back to the opening balances recorded on the
first day of the year so the prior column still reflects the year-opening
state. A separate prior-workspace path is not part of the current workspace
configuration contract.
reporting_profile.fi_statutory.presentation_currency and reporting_profile.fi_statutory.presentation_unit define statement display units. Current supported value is EUR; TEUR is reserved for later.
reporting_profile.fi_statutory.prepared_under_pma controls whether output should include the “prepared under small/micro provisions” indicator for PMA reporting when needed.
reporting_profile.fi_statutory.signature.signers and reporting_profile.fi_statutory.signature.date carry signer metadata and date for statement PDF output. If signer metadata is absent, bus-reports emits a deterministic signature placeholder block.