This document is a description of FINN.no XML namespace. They have been designed to fit with Atom. This specification uses XML Namespaces W3C.REC-xml-names-19990114 to uniquely identify XML element names. Namespace prefix: "finn" : "http://xmlns.finn.no/atom-ad-extensions/1.0".
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this documentation are to be interpreted as described in BCP 14, RFC2119 as scoped to those conformance targets.
The word 'Atom' is referenced to be RFC-4287.
The word 'atompub' is referenced to be RFC-5023.
The elements will reuse existing Atom elements and definitions, any types starting with atom MUST be considered from the Atom spec.
Represents the geographic location where the Ad may be found:
finnLocation =
element finn:location {
atomCommonAttributes,
(extensionElement* & (
finnAddress*,
finnCity,
finnCityDistrict,
finnCountry,
finnPostalCode))
}
finnAddress =
element finn:address {
atomCommonAttributes,
text
}
finnCity =
element finn:city {
atomCommonAttributes,
text
}
finnCityDistrict =
element finn:city-district {
atomCommonAttributes,
text
}
finnCountry =
element finn:country {
atomCommonAttributes,
text
}
finnPostalCode =
element finn:postal-code {
atomCommonAttributes,
text
}Represents a Contact for an Ad. The atom:uri element of the contact will contain a link which can be used for sending email. The contact elements will usually appear on an atom:entry element.
finnContact =
element finn:contact {
atomPersonConstruct,
finnPhone*,
attribute type {contactType}?
}The 'type' attribute is optional and SHOULD be considered have the value 'organization' if it does not appear, or has an unknown value. The 'type' attribute should be considered to have the following set of values:
The set is expandable, and there WILL be a registry where clients can find information about what each 'type' means. User Agents can always interpret unknown values as being equal to 'organization', for interop.
Represents a phone number. This SHOULD be a display value only. User Agents SHOULD NOT rely on phone numbers being represented by a parsable format. Formally the phone element is defined like this:
finnPhone =
element finn:phone {
atomCommonAttributes,
attribute type {
string'fax',
string'mobile',
string'home',
string'work'
},
text
}Conceptually the AData element can be thought of as a container element for Ad data. An AData element can contain Field(s). Formally the adata element is defined like this:
finnAdata =
element finn:adata {
atomCommonAttributes,
attribute model {
atomUri
},
(finnField*
& finnPrice*,
& extensionElement*)
}The model attribute is an IRI to representing a model describing the fields.
The model attribute serves two purposes:
User Agents are expected to have previously downloaded the resource identified by the target IRI, as it is the most common use case.
Fields referenced which does not exist in the model, MUST be ignored by the agent. It is NOT an error having unknown fields, and User Agents MUST handle absence of fields.
Formally the field element is defined like this:
finnField =
element finn:field {
atomCommonAttributes,
attribute name {
atomNCName
},
(attribute value {
text
} | (finnValue|finnField|xhtml:divtext)*
& extensionElement*)
}A field has a name and a value. A name SHOULD be referenced in the model document referenced by the adata element.
A field MAY have a value attribute, and then it will have zero children.
A field MAY have zero or more 'value' elements and those are considered as a List type of construct.
A field MAY have other field elements as children. Those should be considered a Map type of construct.
A field MAY have a xhtml:div element. This should be considered rich text.
A field MAY have textual content. This should be considered simple text.
Formally the value element is defined like this:
finnField =
element finn:value {
atomCommonAttributes,
(text | (finnField & extensionElement*))
}Accuracy is related to a set of coordinates. The scale is equivalent to the one Google use in their maps API.
finnAccuracy =
element finn:accuracy {
atomCommonAttributes,
(text | (extensionElement*))
}This document is a description of FINN.no extensions to OpenSearch.
This specification uses XML Namespaces W3C.REC-xml-names-19990114 to uniquely identify XML element names. Namespace prefix: "f" : "http://xmlns.finn.no/opensearch/1.0"
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this documentation are to be interpreted as described in BCP 14, RFC2119, as scoped to those conformance targets.
The word 'Atom' is referenced to be RFC-4287.
The word 'atompub' is referenced to be RFC-5023.
The elements will reuse a lot of existing Atom elements and definitions, any types starting with atom MUST be considered from the Atom spec.
Elements starting with the os prefix MUST be considered from the OpenSearch namespace.
Formally the template element is defined like this:
fTemplate =
element f:template {
atomCommonAttributes,
attribute href {
text
},
attribute rel {
text
}?
}The 'href' attribute defined to follow the format of URI-templates
The rel attribute is defined to follow the rules of section 4.2.7.2 in the Atom spec, with the additional support for cURIE
Formally the filter element is defined like this:
fFilter =
element f:filter {
atomCommonAttributes,
attribute name {
atomNCName
},
attribute range {
xsd: boolean
}?,
(extensionElement & osQuery)*
}The 'role' attribute SHOULD be set to 'subset'.
The attribute 'f:filter' SHOULD be present with the filter value.
The attribute 'f:from' SHOULD be present if parent element 'f:filter' has the 'range' attribute set to 'true'.
The attribute 'f:to' MAY be present if parent element 'f:filter' has the 'range' attribute set to 'true'.
The presence of f:filter in an Atom document or Opensearch Description document means that User Agents SHOULD consider the f:filter as a source for adding query parameter to the context URI.
For feeds there SHOULD be an atomLink with the rel="self", which SHOULD be used as the context URI.
A filter MAY be applied multiple times.
The filter selection algorithm is out-of-scope for this specification.
Normal query name:
If the 'f:filter' has the 'range' attribute set to 'true', the name of the query parameter should be constructed using the following rule:
Example: https://cache.api.finn.no/iad/search/car-norway
<f:filter name="mileage" range="true">
<os:Query f:from="0" f:to="10000" role="subset"/>
<os:Query f:from="10001" f:to="100000" role="subset"/>
</f:filter>Gives: https://cache.api.finn.no/iad/search/car-norway?mileage_from=0&mileage_to=10000
Formally the sort element is defined like this:
fSort =
element f:sort {
atomCommonAttributes,
attribute name{
atomNCName
},
(extensionElement & osQuery)*
}The presence of f:sort in an Atom document or Opensearch Description document means that User Agents SHOULD look for a f:template element with the "http://api.finn.no/relations/sort" relation.
The URI template MUST have a template variable called {{f:sort}}.
This template SHOULD then be filled out with the selected filter values.
Filling out the template works by finding the interesting 'os:Query' elements with the values that are interesting, and applying the 'f:sort' attribute to the found template.
The selection algorithm is out-of-scope for this specification.