This is an automated email from the ASF dual-hosted git repository.
mbeckerle pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/daffodil-schema.g8.git
The following commit(s) were added to refs/heads/main by this push:
new e75e627 Improvements to follow best practices.
e75e627 is described below
commit e75e6271f8ee586f1f4ec69538ea688cd8a0ecf0
Author: Michael Beckerle <[email protected]>
AuthorDate: Wed Feb 26 17:09:39 2025 -0500
Improvements to follow best practices.
Creates a separate Root, Type, and BaseFormat file now.
Root has no namespace.
Added comments to the files to provide more guidance to schema authors.
Change default to flat style (which was already stated in README.md)
Improve README.md with links to DFDL schema style guide, which is a wiki
page for now, but someday will be on daffodil-site.
Improve README.md with link to daffodil-sbt plugin for more info about
the capabilities that offers for compiling, packaging.
The package string is added to prefix of namespace URI.
DAFFODIL-2976
---
README.md | 23 +++++---
.../$name__camel$BaseFormat.dfdl.xsd | 64 ++++++++++++++++++++
.../$name__camel$Root.dfdl.xsd | 68 ++++++++++++++++++++++
..._camel$.dfdl.xsd => $name__camel$Type.dfdl.xsd} | 36 ++++++++----
.../Test$name__Camel$.tdml | 5 +-
.../test_01.$extension$.xml | 2 +-
src/main/g8/build.sbt | 4 ++
src/main/g8/default.properties | 2 +-
8 files changed, 183 insertions(+), 21 deletions(-)
diff --git a/README.md b/README.md
index e4816c5..61a09b0 100644
--- a/README.md
+++ b/README.md
@@ -28,10 +28,22 @@ sbt new apache/daffodil-schema.g8
```
This command prompts for various properties and creates a bare-bones directory
-structure that follows the recommended [DFDL Schema Project Layout]. This
-includes git and sbt configuration files, a basic DFDL schema file, and [TDML]
+structure that follows the recommended [DFDL Schema Project Layout] and most
recent
+best practices from the [DFDL Schema Style Guide]. This
+includes git and sbt configuration files, basic DFDL schema files, and [TDML]
and test files.
+Once you have generated your schema directory, typing `sbt test` will work and
+run a TDML test. Of course, the initial DFDL schema has no fields, the test
data file is empty, and
+the expected XML Infoset file is an empty element. But, it's working and you
can
+keep it working as you fill in the details of the schema and add tests.
+
+The schema project is set up to use the `daffodil-sbt` plugin for SBT as part
of the
+SBT build and test.
+This provides capabilities to compile your DFDL schema into binary form and
package it for
+distribution.
+You can read more about `daffodil-sbt` here: [Apache daffodil-sbt Plugin]
+
### Properties
The following properties are used to configure the generated DFDL schema
project:
@@ -61,11 +73,6 @@ The following properties are used to configure the generated
DFDL schema project
only be used when namespacing is required to avoid file name
ambiguities.
</dd>
- <dt>daffodil_version</dt>
- <dd>
- the version of Apache Daffodil to add as a dependency, defaults to the
- latest release on maven central
- </dd>
</dl>
## Testing
@@ -87,8 +94,10 @@ Apache Daffodil DFDL Schema Template is licensed under the
[Apache License, v2.0
[Apache Daffodil]: https://daffodil.apache.org/
+[Apache daffodil-sbt Plugin]: https://github.com/apache/daffodil-sbt
[Apache License, v2.0]: https://www.apache.org/licenses/LICENSE-2.0
[DFDL Schema Project Layout]: https://daffodil.apache.org/dfdl-layout/
+[DFDL Schema Style Guide]:
https://cwiki.apache.org/confluence/display/DAFFODIL/DFDL+Schema+Style+Guide
[Giter8]: http://www.foundweekends.org/giter8/
[SBT]: https://www.scala-sbt.org/
[SBT Giter8]:
http://www.foundweekends.org/giter8/testing.html#Using+the+Giter8Plugin
diff --git
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$BaseFormat.dfdl.xsd
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.tru
[...]
new file mode 100644
index 0000000..a77fe1a
--- /dev/null
+++
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$BaseFormat.dfdl.xsd
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+$!
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+!$
+
+<schema
+ xmlns="http://www.w3.org/2001/XMLSchema";
+ xmlns:xs="http://www.w3.org/2001/XMLSchema";
+ xmlns:fn="http://www.w3.org/2005/xpath-functions";
+ xmlns:dfdl="http://www.ogf.org/dfdl/dfdl-1.0/";
+ xmlns:$name;format="camel"$="urn:$package$.$name;format="camel"$"
+ targetNamespace="urn:$package$.$name;format="camel"$"
+ elementFormDefault="unqualified">
+
+ <include
schemaLocation="/org/apache/daffodil/xsd/DFDLGeneralFormat.dfdl.xsd" />
+
+ <!--
+ This file defines a base format for use by all the schema files of this
format.
+
+ Most real DFDL schemas will expand past a single file just to make editing
+ easier and organize the parts of the schema. So it is easiest to start off
+ right away with a separate file for the base format.
+ -->
+ <annotation>
+ <appinfo source="http://www.ogf.org/dfdl/";>
+ <dfdl:defineFormat name="$name;format="camel"$BaseFormat">
+ <!--
+ Place the basic DFDL properties shared by the format below.
+
+ This makes it easy to share them as your format grows into
+ multiple files of DFDL.
+
+ Note on syntax: DFDL properties placed inside a dfdl:format
+ element do not (and cannot have) a "dfdl:" prefix.
+
+ Some properties may be the same as in the GeneralFormat.
+ If they are important properties for the format it is
+ best to list them here anyway. The fallback to GeneralFormat is
+ really to avoid having to mention properties that aren't
+ relevant to the format, but which Daffodil requires anyway.
+ -->
+ <dfdl:format
+ ref="$name;format="camel"$:GeneralFormat"
+ />
+ </dfdl:defineFormat>
+ </appinfo>
+ </annotation>
+
+</schema>
diff --git
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$Root.dfdl.xsd
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$
[...]
new file mode 100644
index 0000000..9e3faaf
--- /dev/null
+++
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$Root.dfdl.xsd
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+$!
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+!$
+<xs:schema
+ xmlns:xs="http://www.w3.org/2001/XMLSchema";
+ xmlns:fn="http://www.w3.org/2005/xpath-functions";
+ xmlns:dfdl="http://www.ogf.org/dfdl/dfdl-1.0/";
+ xmlns:$name;format="camel"$='urn:$package$.$name;format="camel"$'
+ elementFormDefault="unqualified">
+
+ <!--
+ This file defines a root element for the data format.
+
+ You may not need to modify this file.
+ Rather, the details of the format are in the
"$name;format="camel"$Type.dfdl.xsd" file.
+
+ Notice this element is in no namespace, which is recommended for
+ root elements in DFDL schemas. This keeps the DFDL schema compatible with
+ parsing data not only into XML, but into other representations like JSON
which don't
+ have namespaces.
+
+ Use of this root element is entirely optional.
+
+ Tests built into the schema project will use this root element.
+ However, users can use this root element, or use the schema as a library by
+ defining their own local or global element and using the top level complex
type for
+ the format in the "$name;format="camel"$Type.dfdl.xsd" file, just as
+ this root element does.
+
+ It is recommended that top-level root element(s) are in no namespace
+ and contain only a type reference to a complex type defined in the
+ schema's namespace. That is, they are _one-line_ element declarations.
+ -->
+ <xs:import
+ namespace='urn:$package$.$name;format="camel"$'
+ schemaLocation='$name;format="camel"$Type.dfdl.xsd' />
+
+ <xs:annotation>
+ <xs:appinfo source="http://www.ogf.org/dfdl/";>
+ <dfdl:format ref='$name;format="camel"$:$name;format="camel"$BaseFormat'
/>
+ </xs:appinfo>
+ </xs:annotation>
+
+ <xs:element name='$name;format="camel"$'
type='$name;format="camel"$:$name;format="camel"$Type' />
+
+ <!--
+ If you need more root elements just for testing, don't add them here,
+ Add them in the test resources directory so they won't be part of the
+ final DFDL schema
+ -->
+
+</xs:schema>
diff --git
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$.dfdl.xsd
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$pack
[...]
similarity index 56%
rename from
src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$.dfdl.xsd
rename to
src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$Type.dfdl.xsd
index 52e0433..f8c83a3 100644
---
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$.dfdl.xsd
+++
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/$if(namespaced.truthy)$main$else$src$endif$/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/$if(namespaced.truthy)$xsd$else$.$endif$/$name__camel$Type.dfdl.xsd
@@ -17,30 +17,44 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
!$
-
<schema
xmlns="http://www.w3.org/2001/XMLSchema";
xmlns:xs="http://www.w3.org/2001/XMLSchema";
xmlns:fn="http://www.w3.org/2005/xpath-functions";
xmlns:dfdl="http://www.ogf.org/dfdl/dfdl-1.0/";
- xmlns:$name;format="camel"$="urn:$name;format="camel"$"
- targetNamespace="urn:$name;format="camel"$"
+ xmlns:$name;format="camel"$="urn:$package$.$name;format="camel"$"
+ targetNamespace="urn:$package$.$name;format="camel"$"
elementFormDefault="unqualified">
- <include schemaLocation="org/apache/daffodil/xsd/DFDLGeneralFormat.dfdl.xsd"
/>
+ <!--
+ This file contains the definition of the $name;format="Camel"$ data format.
+ -->
+
+ <include schemaLocation="$name;format="camel"$BaseFormat.dfdl.xsd" />
<annotation>
<appinfo source="http://www.ogf.org/dfdl/";>
- <dfdl:format ref="$name;format="camel"$:GeneralFormat" />
+ <dfdl:format ref="$name;format="camel"$:$name;format="camel"$BaseFormat"
/>
</appinfo>
</annotation>
- <element name="$name;format="Camel"$">
- <complexType>
- <sequence>
+ <complexType name="$name;format="camel"$Type">
+ <sequence>
+
+ </sequence>
+ </complexType>
+
+ <!--
+ Note that this file and other files of this schema should not
+ define global elements except for test purposes under the test
+ resources directory.
+
+ Rather only simple or complex types and
+ groups should be defined.
- </sequence>
- </complexType>
- </element>
+ This helps keep the DFDL schema usable not only to create XML
+ from parsing, but usable to parse data to JSON and other
+ formats that do not have namespaces.
+ -->
</schema>
diff --git
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/Test$name__Camel$.tdml
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/Test$name__Camel$.tdml
index 0ade9ff..87f8585 100644
---
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/Test$name__Camel$.tdml
+++
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/Test$name__Camel$.tdml
@@ -29,7 +29,10 @@ limitations under the License.
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
defaultRoundTrip="onePass">
- <parserTestCase name="$name;format="camel"$_01" root="$name;format="Camel"$"
model="$if(namespaced.truthy)$$package;format="packaged"$/$name;format="camel"$/xsd/$endif$$name;format="camel"$.dfdl.xsd">
+ <parserTestCase
+ name="$name;format="camel"$_01"
+ root="$name;format="camel"$"
+
model="$if(namespaced.truthy)$$package;format="packaged"$/$name;format="camel"$/xsd/$endif$$name;format="camel"$Root.dfdl.xsd">
<document>
<documentPart type="file">test_01.$extension$</documentPart>
</document>
diff --git
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/test_01.$extension$.xml
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/test_01.$extension$.xml
index 7046be5..1356de9 100644
---
a/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/test_01.$extension$.xml
+++
b/src/main/g8/$if(namespaced.truthy)$src$else$.$endif$/test/$if(namespaced.truthy)$resources$else$.$endif$/$if(namespaced.truthy)$$package$$else$.$endif$/$if(namespaced.truthy)$$name__camel$$else$.$endif$/test_01.$extension$.xml
@@ -17,4 +17,4 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
!$
-<$name;format="camel"$:$name;format="Camel"$
xmlns:$name;format="camel"$="urn:$name;format="camel"$" />
+<$name;format="camel"$ />
diff --git a/src/main/g8/build.sbt b/src/main/g8/build.sbt
index 359b054..c4579d7 100644
--- a/src/main/g8/build.sbt
+++ b/src/main/g8/build.sbt
@@ -20,6 +20,10 @@ organization := "$package$"
version := "0.1.0-SNAPSHOT"
+// if you need a specific version of Daffodil, you can uncomment and edit
+// this line to refer to a specific daffodil version.
+// daffodilVersion := "00.00.0"
+
// for details about DaffodilPlugin settings, see
https://github.com/apache/daffodil-sbt
enablePlugins(DaffodilPlugin)
diff --git a/src/main/g8/default.properties b/src/main/g8/default.properties
index 9ee0903..0fd181e 100644
--- a/src/main/g8/default.properties
+++ b/src/main/g8/default.properties
@@ -16,4 +16,4 @@
name=format
extension=dat
package=com.example
-namespaced=yes
+namespaced=no
