diff --git a/docs/usage-bods.rst b/docs/usage-bods.rst index 90dd6e3..049577a 100644 --- a/docs/usage-bods.rst +++ b/docs/usage-bods.rst @@ -1,9 +1,36 @@ Flatten Tool for BODS +++++++++++++++++++++ +BODS 0.4 +======== + +Flatten tool can be used to flatten and unflatten BODS 0.4 data. + +Flatten tool has not yet been updated to handle the BODS 0.4 schema. (For the moment the ``--schema`` option should not be used when handling BODS 0.4 data.) This documentation will be updated when the work is complete. + + + flatten and unflatten +--------------------- + +This data standard has a list as the root element, +as opposed to other standards where the root element is a dict with meta data and a list of data. +When flattening and unflattening, use the ``--root-is-list`` option. + +The id element is ``statementId``, so also use the ``--id-name`` option. + +.. code-block:: bash + + flatten-tool flatten -f csv --root-is-list --id-name=statementId -o examples/bods-one-flatten examples/bods-one.json + flatten-tool unflatten -f csv --root-is-list --id-name=statementId -o examples/bods-one-unflattened.json examples/bods-one-flatten + + +BODS 0.3 and previous ===================== +flatten and unflatten +--------------------- + This data standard has a list as the root element, as opposed to other standards where the root element is a dict with meta data and a list of data. When flattening and unflattening, use the ``--root-is-list`` option. @@ -17,7 +44,7 @@ The id element is ``statementID``, so also use the ``--id-name`` option. flatten -======= +------- This data standard has three types of statement - ``entityStatement``, ``personStatement`` or ``ownershipOrControlStatement``. When using flatten, the spreadsheets produced can become very mixed up. @@ -64,10 +91,10 @@ If you want to use Excel mode, you'll need to specify 3 separate output files an flatten-tool flatten --sheet-prefix=3_ownership_ --filter-field=statementType --filter-value=ownershipOrControlStatement -f xlsx -o example1/part3.xlsx example1.json --root-is-list --id-name=statementID unflatten -========= +--------- Schema ------- +~~~~~~ As well as the options above, also pass the ``--schema`` option so that types are set correctly. Note the boolean and the integer in the output. @@ -79,7 +106,7 @@ As well as the options above, also pass the ``--schema`` option so that types ar Order is important ------------------- +~~~~~~~~~~~~~~~~~~ In the BODS schema, statements must appear in a certain order. Each of the ``entityStatements`` or ``personStatements`` referenced by a particular ``ownershipOrControlStatement`` must appear before that particular statement in the ordered array. @@ -118,7 +145,7 @@ For instance: * 3main-control-own.csv create-template -=============== +--------------- You can run this directly on ``bods-package.json``: @@ -209,3 +236,4 @@ The advantages are: +