There are currently (5) existential flags for WOF documents that map to the "standard places response" (SPR) interface. The SPR is meant to be a minimum common response for all services that provide a public interface for accessing WOF documents.
The SPR itself remains to be fully and properly documented.
Existential flags can be used to filter records on ingest. For example the go-whosonfirst-pip-v2 package allows you to filter records to index by one or more existential flags:
https://github.com/whosonfirst/go-whosonfirst-pip-v2/blob/master/app/indexer.go#L98-L175
Or responses can be filtered to exclude records with one or more existential flags. For example the same go-whosonfirst-pip-v2 package does this using an internal FilterSPR method:
https://github.com/whosonfirst/go-whosonfirst-pip-v2/blob/master/filter/filter.go#L21
And the whosonfirst-www-api package does the same in two different places, depending on the backing service it is talking to:
Typically all of these flags are derived from other properties in a document although any of them may be manually assigned. Detailed rules for each flag are discussed below but at a high level it breaks down like this:
is_current serves as a short-hand filter for pruning or limiting results. Its value is dependent on placetype and derived for other properties in a record. For example both a venue that has a closed (is no longer open for business) and a neighbourhood that has been marked as deprecated (because of bunk data) will be marked as no longer current or mz:is_current=0.
is_ceased indicates that the place in question is no longer a present concern. For example a venue (business) that has closed and the former Yugoslavia will both be flagged as mz:is_ceased=1. Generally this value is derived by testing for the presence of the edtf:ceased property.
is_deprecated indicates that a record is not longer considered valid and should not be used anymore. Many records that are deprecated will also be superseded by a valid record but that is not required. Genereally this value is derived by testing for the presence of the edtf:deprecated property.
is_superseded indicates that a record has been superseded by another record. There are many reasons why one record may supersede another record ranging from a "major" lifecycle change or a record being deprecated. Generally this value is derived by testing for presence of and a non-zero length of the wof:superseded_by property.
Lifecycle changes are documented in: [ LINK ]
It is important to note that a record may be both superseded and superseding at the same time.
is_superseding indicates that a record is superseding one or more records. As with the is_superseded property here are many reasons why a record many supersede another. Generally this value is derived by testing for the the presence of and a non-zero length of the wof:supersedes property.
It is important to note that a record may be both superseded and superseding at the same time.
Unknown.
False
True
The following flags are currently not part of the standard existential flags. Each is described in the whosonfirst-properties/properties/mz documented.
-
mz:is_approximate
- mz:is_funky
-
mz:is_official
All of these properties are manually assigned rather than derived. None of these properties are required and may not be present in a WOF document. It is not clear whether these should be added to the SPR.
Currently the SPR interface and corresponding existential flags are only implemented in the Go language.
The relevant section of the SPR interface, as defined in the go-whosonfirst-spr package, looks like this:
type StandardPlacesResult interface {
...
IsCurrent() flags.ExistentialFlag
IsCeased() flags.ExistentialFlag
IsDeprecated() flags.ExistentialFlag
IsSuperseded() flags.ExistentialFlag
IsSuperseding() flags.ExistentialFlag
}
The interface for existential flags (as returned by the SPR interface), as defined in the go-whosonfirst-flags package, looks like this:
type ExistentialFlag interface {
StringFlag() string
Flag() int64
IsTrue() bool
IsFalse() bool
IsKnown() bool
MatchesAny(...ExistentialFlag) bool
MatchesAll(...ExistentialFlag) bool
String() string
}
The go-whosonfirst-geojson-v2 defines the following SPR (and existential flags) for Who's On First GeoJSON files:
The go-whosonfirst-geojson-v2 defines the following SPR (and existential flags) for plain old GeoJSON files:
(Hint: everything returns -1)
These are the rules that the go-whosonfirst-geojson-v2/properties/whosonfirst method use for determing the value of an existential flag for a WOF GeoJSON feature:
- If the
mz:is_currentproperty is present return that - If the
IsDeprecated()method returns a flag whoseIsTrue()andIsKnown()methods return true return an existential flag of0 - Is the
IsCeased()method returns a flag whoseIsTrue()andIsKnown()methods return true return an existential flag of0 - If the
IsSuperseded()method returns a flag whoseIsTrue()andIsKnown()methods return true return an existential flag of0 - Otherwise return an existential flag of
-1
- If the
edtf:deprecatedproperty is present 1b. and its value isureturn an existential flag of-11c. and its value isuuuureturn an existential flag of-12d. and is not empty return and existential flag of1 - Otherwise return an existential flag of
0
- If the
edtf:deprecatedproperty is present 1b. and its value isureturn an existential flag of-11c. and its value isuuuureturn an existential flag of-12d. and is not empty return and existential flag of1 - Otherwise return an existential flag of
0
- If the
wof:superseded_byproperty is present and is an array and contains one or more WOF ID, return an existential flag of1 - Otherwise return an existential flag of
0
- If the
wof:supersedesproperty is present and is an array and contains one or more WOF ID, return an existential flag of1 - Otherwise return an existential flag of
0
The choice and use of EDTF for dates is discussed in detail in the whosonfirst-dates repository. The thing to note for the purpose of this document is that dates in many WOF records MAY have a value of uuuu which is EDTF shorthand for unknown or undefined. It should not be confused with a valid EDTF date string.