mbeckerle commented on code in PR #205:
URL: https://github.com/apache/daffodil-site/pull/205#discussion_r2551592653
##########
site/best-practices/dfdl-best-practices.md:
##########
@@ -0,0 +1,713 @@
+---
+layout: page
+title: Best Practices Guide for DFDL Schema Authors
+group: nav-right
+---
+<!--
+{% comment %}
+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.
+{% endcomment %}
+-->
+
+## Table of Contents
+{:.no_toc}
+<!-- The {: .no_toc } excludes the above heading from the ToC -->
+
+1. yes, this is the standard Jekyll way to do a ToC (this line gets removed)
+{:toc}
+<!-- note the above line {:toc} cannot have whitespace at the start -->
+
+
+# Introduction
+
+This page is a collection of notes on how to create DFDL schemas to obtain
some real benefits:
+- Minmizes XML and XSD namespace complexity
+- Provides composition properties so DFDL schemas can be reused as libraries
in larger schemas
+- Ensures compatibility of the schema with more restrictive infosets than XML.
+ For example: JSON, Apache NiFi Records, or Apache Spark Structs.
+- Ensures portability of the DFDL schema for use to validate XML infosets
+ using multiple different _XML Schema Validation libraries_ such as [Xerces
C](
+ https://xerces.apache.org/xerces-c/) and
[libxml2](https://gitlab.gnome.org/GNOME/libxml2).
+
+The [DFDL Training](/dfdl-training) page lists several example schemas which
follow this style guide
+fully which you can use as good starting points.
+
+This set of notes represents best practices after learning _the hard way_ from
many debugging
+exercises and creating a wide variety of DFDL schemas from small teaching
examples to large
+production schemas for major data formats with more than 100K lines of DFDL.
+
+For those familiar with XML Schema (XSD) design patterns, our schema style is
a variation of
+what is called the
+[_Venetian Blind_ pattern](
+https://www.balisage.net/Proceedings/vol25/print/Bruggemann-Klein01/BalisageVol25-Bruggemann-Klein01.html),
Review Comment:
URLs to be factored out into links.yml file
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
