Choosing a Good Specification

Choosing a specification is mostly based on:

• Correctness - is the specification suitable for your need
• Trust - will the organization be around in 10 years
• Popularity - is the specification actually used in the wild

The OGC Specifications are preferred as they are available to the public and others can verify the correctness of your interface. The XML Schemas are often published onto the web which is a great help.

• The document name and abstract provide good material for package-info.java
• The documents usually contain UML diagrams and discussion used to define the interfaces
• The XML Schema descriptions are the best source of javadoc information

The ISO Specifications are only okay as they are available for purchase only, please be sure to provide enough information in your javadocs that a user can get by with only your interface to guide them

• The documents provide a good Name and Introduction used for the package-info.java
• A section of UML Diagrams used to create the classes and codelists
• A Data Dictionary used to create javadocs

Using a Specification

The following pages contain the details on converting a specification into geoapi packages and interfaces.

• Specification Name and Description — The specification name and description will be used to figure out your java package and package-info.java.
• UML Diagram — The vast benefit of these specifications is communicated via their included UML diagrams. We use this information to define the names of our interfaces, methods and fields.
• Data Definition — The data definition in a specification are usually provided as a "Data Dictionary" or "XML Schema". This information is where we find details for our javadocs.

Is this legal?

Creating an implementation based on a standard is expected use for a specification, ISO in particular has some guidelines of 20% if I remember - but since we are focused on such a small part of the specification (description) we are well within our comfort zone. The vast majority of the information we are interested in is transfered straight into Java code and annotations.