Kudos to Fabio and LegalDocML TC [ was: Table of content for the Customi

Subject: Kudos to Fabio and LegalDocML TC [ was: Table of content for the Customizing Akoma Ntoso document]

Kudos to Fabio and his development/spec teams on the posting below [1a], about Akoma Ntoso (schema) customizations, restrictions, extensions, etc

https://lists.oasis-open.org/archives/legaldocml/201805/msg00002.html

Fabio references what I consider a very cool online tool "AKN4UN Subschema Frontend", reminding me of a similar tool created for the TEI

TEI Guidelines Pizza Chef

http://www.tei-c.org/Vault/P4/pizza.html

"...build a DTD that contains just the elements you want, suitable for use with any XML processing system"

I had occasion a few years to discuss and praise this technical design in Akoma Ntoso, cribbed up from several resources, and perhaps how in need of revision, but here's the excerpt from my cribbing:

[Akoma Ntoso schema and its implementations]

"... it is expected that developers of these applications/implementations, as well as end user customizations, will modify the Akoma Ntoso schema for use in various jurisdictions, exploiting the extensibility models and customization features. Why "modify"? Because that's the way it works: customization and extension are key to the design.

[resource - needs update] discusses "customizations to the general Akoma Ntoso schema that imply performing actual modifications to the actual schema". A fuller treatment of customizations, explaining Akoma Ntoso as "more like a Lego box full of building bricks," is presented by Flavio Zeni in the April 2014 OpenParl News Brief:

"We can say that Akoma Ntoso is a meta-schema that allows you to build your own schema: it provides the building blocks for different organisations to use to build their own very individual schemas. Having organisations using similar building blocks, identifying these blocks in a similar fashion goes a long way to allow greater integration and exchange of documents as well as reusability of software tools..."

Akoma Ntoso thus provides the building blocks for you to create the specific schema you need, and it allows you to add new (markup) elements and modify base schema elements if you need them. AKN defines the core vocabulary and allows use of the vocabulary and atomic component markup structures to be composed variably for different jurisdictions and their legal genres..."

In the current version of the tool at today's location, you can see (enjoy!) how the schema tool works:

AKN4UN Subschema Frontend (1.0 beta)

for Release 30/03/2017 - Akoma Ntoso 3.0 - Published 06/06/2017

http://akn.web.cs.unibo.it/akgenerator/

UN-specific Combinations

http://akn.web.cs.unibo.it/akgenerator/#tabs0

Available Modules

http://akn.web.cs.unibo.it/akgenerator/#tabs1

Heading Rules

http://akn.web.cs.unibo.it/akgenerator/#tabs2

Document Rules

http://akn.web.cs.unibo.it/akgenerator/#tabs3

Custom Rules

http://akn.web.cs.unibo.it/akgenerator/#tabs4

See (maybe with updates from Fabio or Monica)

"Akoma Ntoso - why-what"

https://mysociety.sayit.mysociety.org/akoma-ntoso-why-what

Congratulations also to the members of the C on recent approval for a Candidate OASIS Standard

OASIS LegalDocumentML (LegalDocML) TC

https://www.oasis-open.org/committees/legaldocml/

Monica Palmirani [ monica.palmirani@unibo.it ] Chair

Fabio Vitali [ fabio@cs.unibo.it ] Chair

- Robin

[1a]

On Tue, May 8, 2018 at 11:37 AM, Fabio Vitali <fvitali@gmail.com> wrote:

Dear all,

as requested here is the table of content of the document on the customization of Akoma Ntoso. Of course most of it will resemble my old document that I shared the, and am attaching again here.

1 The customization of XML schemas
What it means to customize an XML Schema in a conservative way, in order to respect the fundamental good properties of the base schema and introduce only those constraint you really are interested in.
Fundamental law: all documents valid according to the customized schema must be valid according to the base schema. Ways to customize are basically restrictions, extensions and translations.
Fundamental law to customize Akoma Ntoso: respect patterns, compliance rules and metadata.

2 Restricting Akoma Ntoso
What it means to restrict a schema: add limits to the allowed content model of elements, to allowed values of attributes, etc. In short: go right ahead and do your worst, you will not be able to break the schema.
How to do that: you can create your own schema, or use existing tools such as the custom schema generator available at XXX (currently http://akn.web.cs.unibo.it/akgenerator/ but will have to move somewhere else).

3 Extending Akoma Ntoso
What it means to extend a schema in a conservative way. Basically there are only a few things you can do so as not to break things. Breaking Akoma Ntoso is even simpler, so this is a delicate thing to do, but Akoma Ntoso provides you with ways to safely extend things:
3.1 The element <foreign>
3.2 Generic elements
3.3 The <proprietary> section and other ways to add custom metadata

4 Other ways to customize the schema
4.1 Custom attributes (yes you can)
4.2 Custom elements (you shouldn't, but if you need you can, as long as you respect the patterns)

5 Translations
Basically, you should not. Really, you shouldn't. But if you insist, there are ways to do so in a safe manner. Generate a correct subschema in the original English language, then translate in your own language all the elements, attributes and attribute values EXCEPT FOR AKOMA NTOSO, and generate a custom namespace that we can recognize, and generate a translation map (which MUST BE 1-1 with the original language) and provide a link to the translation map in the schema.

Ciao

Fabio

--

Fabio Vitali The sage and the fool
Dept. of Informatics go to their graves
Univ. of Bologna ITALY alike in this respect:
phone: +39 051 2094872 both believe the sage to be a fool.
e-mail: fabio@cs.unibo.it Where, then, may wisdom be found?
http://vitali.web.cs.unibo.it/ Qi, "Neither Yes nor No", The codeless code

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

Robin Cover

legaldocml message