PlanningAlerts

4 ATDIS-1.0.2 Application Tracking Data Interchange Specification

4.1 Components of the specification

Figure 2 presents the four high-level components of the Specification:

Figure 2: Components of the specification

• Feed: defines a publicly available source of application tracking data. For example, each complying Council would provide a single feed for application tracking data.
• Schema: defines the data elements that make up individual application tracking records. Examples include "date", "location" and "reference".
• Use cases: defines the agreed use cases for which ATDIS data can participate. Examples include "enquiries" and "subscriptions".
• Channels: defines the channels over which ATDIS data can be delivered. Examples include RSS, REST/[JSON, XML] and Browser.

4.2 Feed

Any compliant source of application tracking data is referred to as a feed. A feed is defined by a standard web address of the form:

Figure 3: Feed web address format

Where

• Protocol: assume HTTP, but HTTPS can be used by a Council if required
• Web address: the fully qualified web host name for the Complying Authority. By convention, this should be the same as the URL used to access the Council's publicly available web site.
• Feed prefix: component of the URI that indicates a complying feed.
• Schema version: component of the feed prefix that indicates the version of the schema offered by the feed.
• Unique Authority identifier: The UAI uniquely identifies an authority for applications published by an ATDIS-compliant authority. This allows for applications within one LGA to be referenced uniquely by documents within another authority without the need to ensure that dat_id values are unique across all participants.
• Globally Unique DAT Id: When combined wit the UAI, the dat_id for an application creates a globally unique identifier for an application that is portable between LGA jurisdictions.

Notes

• There are a number of options for how the schema version number might be encoded into the feed URL. The above format (where the version is encoded into the URI) is the simplest mechanism, but it is also possible to encode version number with an HTTP header variable, with a query string parameter, or by using content negotiation. There is a vibrant and passionate debate about the best way to version URLs for access to resources that shows no prospect of being settled soon. Therefore, for the purposes of ATDIS-1.0.2, a simple URI-encoded version string is proposed. If content negotiation becomes the preferred standard, then this it is relatively easy to change the prefix in a future release.
• Given a version of the specification of the form MAJOR.minor.patch, it is assumed that all patch versions of the same major/minor version remain semantically and syntactically compatible with each other. Minor may introduce new items but will not remove any existing items. Major versions may make changes to the schema that are not backwards compatible.

4.3 Schema

The schema defines the specific data elements that are published in a compliant ATDIS-1.0.2 feed. The schema has a defined structure, broken down into one or more application records, which are further decomposed into blocks and fields.

To comply with the Specification, a feed must support the basic conceptual structure of a list of application records, within which the feed will provide blocks and fields for each application record.

Record types can be mandatory or optional. Within a record, fields can be mandatory or optional.

A feed must include all mandatory record types. A feed may include any of the optional record types.

For each mandatory record type, the feed must include all mandatory fields, and may include any of the optional fields.

If a feed chooses to include a record type then it must include all mandatory fields for that record type. A feed can chose whether or not to include any optional fields within a block.

If a field is empty, then it should be populated with the appropriate JSON null value. For example:

{"field": null}

Figure 4 describes the conceptual structure of a complying feed:

Figure 4: Feed structure

There are seven record types defined within the Specification:

1. Info
2. Reference
3. Locations
4. Events
5. Documents
6. People
7. Extended

The following sections describe the semantics of each of the seven record types that make up the Specification. For each record type, the Specification indicates whether the record type is mandatory or optional, and within each record type, which fields are mandatory or optional.

4.3.1 Info [Mandatory]

The info record is the top-level block that contains unique identifying information about a single development application. The info record must contain the following fields:

M/O	Fields		Notes
M	dat_id		An id that uniquely identifies the application within this authority
M	development_type		Relevant category requested by Planning and Infrastructure for the Local Development Performance Monitoring program
M	application_type		The Agency needs to collect statistics on types of application so that it can assess the effectiveness of different assessment pathways. Valid types are: DA, CDC, S96, Review, Appeal, Other.
M	last_modified_date		The date of the last change to this record
M	description		A short, human readable description of the application
M	authority		Identifying information for this Authority
M		ref	The unique Authority identifier (UAI) for this authority
M		name	Human readable Authority name
M	lodgement_date		Date the application was lodged with the Authority
M	determination_date		Date that the application was determined at the Authority
M	determination_type		One of the determination types specified below
M	status		Current status of the application with the Authority
O	notification_start_date		Start date for notification period of application
O	notification_end_date		End date for notification period of application
O	officer		Name of responsible officer from the Authority
O	estimated_cost		Estimated cost of the work described by the application
O	related_apps		List of fully qualified authority/ref/dat_id for related applications

Notes

• If the field dat_id contains non-URL characters in its raw form, then it must be URL-encoded so that it can form part of a valid URL.

• The value development_type should be the relevant category requested by Planning and Infrastructure for the Local Development Performance Monitoring program. ATDIS seeks to reduce Council manual work effort spent each year extracting, collating and reporting DA data for the annual Local Development Performance Monitoring report prepared by Planning and Infrastructure. In this context, development_type is a key piece of data needed for this report.

• The field last_modified_date captures the date at which the authority last modified the record. This allows consuming systems to know if an application changes over time. The last_modified_date field in the info record should capture the date that the application was last changed in the underlying source system. Vendors are responsible for determining which internal date in their system is the relevant field to use to populate this value. Conceptually, the last_modified_date field is the business concept that represents the date/time that the application was changed.

• Dates can be specified with or without time information. For example, the following are both valid date values (see also 4.3.8):

"determination_date": "2013-06-20T02:01:07Z"

"determination_date": "2013-06-20"

• If the application does not have a determination date (yet, or at all), the value “null” should be specified for the determination_date field.

• The notification_start_date and notification_end_date are optional fields. Vendors are free to populate this value if it is available in the source system.

• The contents of determination_type and should be one of the values:

  • Pending
  • Refused by Council
  • Refused under delegation
  • Withdrawn
  • Approved by Council
  • Approved under delegation
  • Rejected

• If the application does not have a notification period at all, the value “null” should be specified for the notification_start_date and notification_end_date fields.

• The contents of estimated_cost and should be a formatted currency string in Australian Dollars, of the form “$300,000”.

• If an application is related to other applications either within this LGA or in another LGA, then related_apps may contain a list of references to other applications. The reference should include the authority/ref value for that LGA as well as the dat_id in each case. The reference should be a URI that includes the protocol and the globally unique application id followed by the dat_id and .json. The specification does not prescribe the type of the relationship, other than to say that if this field is included, consuming systems should assume that the other applications are related to this one in some form. The intent of this field is to capture the relationship between applications with different application numbers.

• If a consuming system accesses a specific record using the globally unique identifier, the System should return data for just the single application record that was asked, and no others.

• Any globally unique id used in related_apps should also include the format (.json) in the URL.

4.3.2. Reference [Mandatory]

The reference record contains links to the original source material for the application at the Complying Authority. It can optionally contain a link for where Residents can comment on the application at the Complying Authority. In both cases, the links to URLs captured in the reference block would take the user to another location on the Complying Authority's web site.

The content behind the more_info_url and comments_url values must link to an endpoint that directly shows the information for the specific development application. The underlying content must be directly accessible without authentication, cookies or other limiting requirements for the consuming system. The data and behaviour of the pages at these links is beyond the scope of the ATDIS-1.0.2 Specification.

The reference record must contain the following fields:

M/O	Field	Notes
M	more_info_url	Web address for more information about this application
O	comments_url	Web address for commenting on this application

4.3.3 Locations [Mandatory]

The locations record is designed to provide consumers with information about the geographic locations of the development application. Because not all Authorities have access to geographic information for their development applications, parts of this record are optional. The feed must include the address and land_title_ref attributes within each location record.

It is mandatory that feeds provide the location record with the address and land_title_ref fields, and it is anticipated that future versions of the Specification will promote the coordinates field into mandatory compliance.

Because some applications cover multiple land parcels, the location record is comprised of a list of location blocks under a single locations list field.

M/O	Field				Notes
M	locations				Composite record containing list of locations related to this app
M		address			Human readable street address for the application
M			street		Street name for land parcel
M			suburb		Suburb name for land parcel
M			postcode		Postcode for land parcel
M			state		State for land parcel
M		land_title_ref			Composite record containing Land Title Office references
M			torrens | other		Type of land title reference: torrens | other
M				lot	Lot number
M				section	Section number, or “null”
M				dpsp_id	DP/SP identifier
O		geometry			Composite record containing geographic coordinates (GeoJSON format)

Notes

• The locations record must contain at least one location field, but can contain more than one.

• The contents of land_title_ref can be either torrens or other. In the case of torrens, the field must include a specification of lot, section and dpsp_id. In the case of other the specification can include whatever field values are appropriate for that type.

• In each case the values for lot, section and dpsp_id should all be captured as strings.

• When used, GPS coordinates must make use of the WGS84 datum as per "Earth Gravitational Model 2008 (EGM2008)”. See: http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/index.html for details.

• The format for geographic coordinates must use the GeoJSON specification as per: http://geojson.org/geojson-spec.html#geojson-objects

• The simplest compliant version of a geometry instance would be a Point of the form:

{ "type": "Point", "coordinates": [100.0, 0.0] }

Point coordinates are in x, y order (easting, northing for projected coordinates, longitude, latitude for geographic coordinates). For more advanced geometric types, please refer to the GeoJSON specification.

• As geometry is optional for the Location block in ATDIS-1.0.2, there is no requirement to specify the kinds of geometric data for an application. However, if a feed is supplying geometric data, then it must be formatted according to the GeoJSON specification.

• In general, the dpsp_id will start with either the letters SP or DP, and be followed by a number, but there will be cases where this does not apply.

• A title reference does not always include a section number. If the section value in land_title_ref is not available, then it should be populated with the value “null”.

• When referencing a subdivision, Vendors and Councils should use the original parcel street numbers and/or lot references. In the case of a subdivision, then the pre- subdivision data should be used.

4.3.4 Events [Mandatory]

The events record contains a list of events that have occurred against the application since lodgement. The events record must include a list of events, where each event has an id, date and description. Inclusion of an event_type and status is optional.

M/O	Field		Notes
M	events		Composite record containing a list of events for the application
M		id	Internal id of event raised against application
M		timestamp	Date+time the event occurred
M		description	Short, human readable description of the event
O		event_type	Authority-specific event type
O		status	Authority-specific event status code

Notes

• This version of the specification does not define a list of valid event_types, so the contents of this field can be Vendor or Council specific.

• The value for id should be a string. The value should be unique from the perspective of the authority such that it can be used as a reference for the underlying event.

• The system should produce events that are ordered by [timestamp, id]. In systems where all events generated on the same day are given the same timestamp, then those systems should order the ids so that they are non-decreasing. Consuming systems should assume that ordering the events in terms of [timestamp, id] places them into the sequential order in which they occurred.

• In this context, the events record means any kind of activity that can occur against an application. For example, “tasks" and "workflows" would be synonyms for “events”. The specification does not dictate the type of event, but rather, that if an event of any type is captured, then this is the format in which it needs to be articulated.

4.3.5 Documents [Mandatory]

The documents record contains a list of references (as links) to documents that relate to the application. The documents record must include a list of documents, where each document has a ref, title and a link (in the form of a URL) to the location where the document can be downloaded.

M/O	Field		Notes
M	documents		Composite record containing a list of documents for the application
M		ref	Internal reference of document for this application
M		title	Short, human readable title of the document
M		document_url	URL to location of document for download

4.3.6 People [Optional]

The people record contains a list of people that relate to the application. As an optional record type, this block can be populated as required by an LGA. However, if it the people record is included at all, then it is assumed to include a list of people, where each person has a name and a role indicating their responsibility with the application. Optionally, the person record can include contact information.

M/O	Field		Notes
M	people		Composite record containing a list of people related to the app
M		name	Name of person related to the application
M		role	Authority-specific role type for the person with respect to the app
O		contact	Authority-specific contact information for the related person

4.3.7 Extended [Optional]

The extended record is specifically designed to allow ATDIS-1.0.2 compliant feeds to include any additional information that might be relevant to an application. The contents of the extended record is not specified, and left up to the ATDIS Vendor and Complying Authority to populate as they see fit. There are no mandatory or optional fields for the extended record. Consuming systems should expect its existence, but are not required to do anything with data contained within it.

M/O	Field	Notes
Not Specified

4.3.8 Date Formats

Any field within the schema of the form *_date or timestamp should be treated as an ISO-8601 date format. See: http://www.w3.org/TR/NOTE-datetime for details.

4.4 Other Technical Considerations

4.4.1 Encoding

All data in ATDIS requests should be encoded using UTF-8, and all data returned by ATDIS-compatible systems should be returned in UTF-8 encoding. See http://en.wikipedia.org/wiki/UTF-8 for details.

---

6.4 Paging

In some circumstances, the data for a particular ATDIS query might be larger than is sensible to return in a single response. In this case, the feed can use paging to indicate to the client that the server has more data available. For example, a paged response to a request for all items within a postcode might look like this:

{
  "response": [
    {
      "application": {
        "info": {
          "dat_id": "DA2013-0381",
          “last_modified_date”: “2013-04-20T02:01:07Z”,
          "description": "New pool plus deck",
          "authority": "Example Council Shire Council",
          "lodgement_date": "2013-04-20T02:01:07Z",
          "determination_date": "2013-06-20T02:01:07Z",
          "notification_start_date": "2013-04-20T02:01:07Z",
          "notification_end_date": "2013-05-20T02:01:07Z",
          "status": "OPEN"
        },
        "reference": {
          "more_info_url": "http://www.examplecouncil.nsw.gov.au/atdis/1.0/applications/DA2013-0381"
        },
        "locations": [
          {
            "address": "123 Fourfivesix Street Neutral Bay NSW 2089",
            "land_title_ref": {
              "lot": "10",
              "section": "ABC",
              "dpsp_id": "DP2013-0381"
            }
          }
        ]
      }     
    },
    {
      "application": {
      ...
      }
    }
  ],
  "count": 2,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 25,
    "count": 100,
    "pages": 1
  }
}

In this format, the returned data is split up into three sections: 

• response: contains the raw data of the response, paged according to the pagination block
• count: the number of items returned in this response
• pagination: information about how the returned data was paged relative to the full set of data available for that query. Within the pagination block, the following items indicate how the data was paged:
  • previous: the page number of the immediately preceding page, or null if this is the first page
  • next: the page number of the immediately following page, or null if this is the last page
  • current: the page number of the current page
  • per_page: the number of paged items returned per page
  • count: the total number of items available from the underlying data, unpaged
  • pages: the total number of pages available from the underlying data

Notes

• Paged data is at the discretion of the feed producer.
• In all cases, the response block must be provided by the feed producer, regardless of whether or not the feed is producing paged data.
• In a feed cannot handle pagination, then it can leave out the count and pagination blocks

Because back-end systems page data in a variety of different ways, specification of paging has been set at L2 for the ATDIS-1.0.2 version of the specification. However, Vendors should be aware that the paging specification would be promoted to L1 for the next point release, and that all responses should include the response block when returning data to the consuming system.