decisions.yaml · Property Ontology

yaml261 lines12.3 KB
1decisions:
- id: DEC-001
  topic: upper_ontology
  decision: defer
  status: accepted
  candidates_considered: [BFO-2020, DOLCE, GIST]
  rationale: >
    The ontology is a standalone application vocabulary for AI grounding and
    cataloguing over a single research corpus. No cross-domain reasoning
    requirement exists. Continuant/occurrent and role/realizable distinctions
    are applied informally (Role classes, Event/Activity classes) without
    importing BFO axioms. Revisit if the property-intelligence platform needs
    to integrate with BFO- or GIST-based enterprise ontologies.
  evidence: []
  affects: [architecture]
  date: "2026-09-14"
17
- id: DEC-002
  topic: import_strategy
  decision: reuse_by_iri_without_import
  status: accepted
  rationale: >
    PROV-O (prov:Agent, prov:Activity, prov:Entity, prov:wasDerivedFrom),
    SKOS, Dublin Core Terms and XSD are referenced by IRI. No owl:imports is
    declared, so the reasoning environment stays small and version drift is
    avoided. schema.org, W3C ORG and GeoSPARQL are recorded as candidate
    mappings only (skos:closeMatch / rdfs:seeAlso) because their definitions
    were not compared against pinned versions during this build.
  evidence: []
  affects: [architecture, mappings]
  date: "2026-09-14"
32
- id: DEC-003
  topic: role_modelling
  decision: role_participation_pattern
  status: accepted
  rationale: >
    The sources repeatedly describe the same party in different capacities:
    an owner can be an operator, an operator can be the owner's tenant and the
    resident's landlord, an owner-occupier can be a provider. Owner, Investor,
    Operator, Resident, PropertyManager, Lender, Insurer, Developer, Regulator
    are therefore modelled as named individuals of pbo:Role (also SKOS concepts
    in the RoleScheme) realised through a pbo:Participation node (party, role, agreement/property/activity context,
    optional validity dates), not as subclasses of Person/Organisation.
    Application-level convenience properties (pbo:ownedBy, pbo:managedBy)
    are retained as shortcuts and declared as such.
  evidence: [EV-050, EV-062, EV-071, EV-084]
  affects: [TERM-Participation, TERM-Role, CQ-003]
  date: "2026-09-14"
50
- id: DEC-004
  topic: event_relation_pattern
  decision: first_class_agreement_and_authorisation_nodes
  status: accepted
  rationale: >
    Agreements (leases, head leases, subleases, management agreements) and
    authorisations (planning approvals, registrations, licences, accreditations)
    carry parties, jurisdiction, term, rent, thresholds, validity and source.
    They are modelled as first-class classes rather than binary properties so
    that CQ-001 to CQ-003 can be answered without RDF reification. Simple
    binary relations (pbo:locatedIn, pbo:governedBy) stay binary.
  evidence: [EV-060, EV-061, EV-090]
  affects: [TERM-Agreement, TERM-Authorisation, CQ-001, CQ-003]
  date: "2026-09-14"
65
- id: DEC-005
  topic: taxonomy_vs_class_hierarchy
  decision: skos_for_classification_values
  status: accepted
  rationale: >
    Investment strategies, ownership structures, operating models, accommodation
    types, lease types, tenant configurations, agency business models, risk
    categories, metrics, building classifications, tax classifications,
    authorisation types, tenant segments and data-access tiers are classification
    values whose sources disagree on boundaries and which are combined freely
    (a rooming house can be operated under a master lease by a company). They are
    SKOS concepts in named schemes, bound to OWL classes through classification
    object properties. Each concept is also typed as an individual of its kind
    class (pbo:OperatingModel, pbo:InvestmentStrategy, ...) so that object
    properties such as strategyUsesOperatingModel have a proper OWL range
    (PAT-003). OWL subclassing is reserved for structural type semantics
    (Agreement subtypes, Authorisation subtypes, PropertyAsset subtypes,
    InformationArtefact subtypes) where every instance genuinely is-a parent.
  evidence: [EV-020, EV-021, EV-040, EV-075]
  affects: [taxonomy.ttl, ontology.ttl]
  date: "2026-09-14"
87
- id: DEC-006
  topic: measurement_pattern
  decision: metric_observation_node
  status: accepted
  rationale: >
    Financial figures in the corpus are always qualified by basis, assumptions,
    publisher and date, and the same metric (gross yield) is reported with
    conflicting values. A pbo:MetricValue node (metric concept, numeric value,
    unit, basis note, scenario or property it describes, source) is used instead
    of bare datatype properties so that CQ-004 and CQ-011 can be answered and
    conflicts preserved. Scenario assumptions reuse the same node type with
    pbo:assumes; results use pbo:yields.
  evidence: [EV-100, EV-101, EV-110]
  affects: [TERM-MetricValue, TERM-FinancialScenario, CQ-004, CQ-011]
  date: "2026-09-14"
103
- id: DEC-007
  topic: regulatory_threshold_pattern
  decision: threshold_node_on_regime
  status: accepted
  rationale: >
    Occupancy thresholds (four or more residents, 1-3 rooms with bond, nine
    bedrooms / 12 persons / 300 m2, five lets / 300 m2) are the single most
    decision-critical facts in the corpus. They are modelled as
    pbo:OccupancyThreshold nodes attached to a pbo:RegulatoryRegime with
    thresholdKind (SKOS), comparison, value, unit and effect, rather than as
    literal properties, so that jurisdictions with multiple thresholds and
    exemptions can be represented and queried (CQ-002).
  evidence: [EV-091, EV-092, EV-093, EV-094]
  affects: [TERM-OccupancyThreshold, CQ-002]
  date: "2026-09-14"
119
- id: DEC-008
  topic: source_conflict_resolution
  decision: preserve_conflicts_as_disputed
  status: accepted
  rationale: >
    Yield claims (5%, 8%, 8-12%, 10-12%+, 10-15%, 15-18%), coliving break-even
    (6-12 vs 12-18 months), rooming-house definitions (four or more unrelated
    tenants vs five studios vs six bedrooms) and vacancy behaviour (lower vs
    higher) conflict across sources. No source is authoritative over the others
    on these points, so the conflicts are preserved as evidence records with
    distinct MetricValue instances and listed in model.yaml unresolved_issues.
    Government/regulator sources (ATO, RTA, Business Queensland) outrank
    commercial and forum sources only on the legal/tax matters they address.
  evidence: [EV-110, EV-111, EV-112, EV-120]
  affects: [CQ-011, unresolved_issues]
  date: "2026-09-14"
136
- id: DEC-009
  topic: domain_range_policy
  decision: conservative_domain_range
  status: accepted
  rationale: >
    rdfs:domain / rdfs:range are asserted only where the inference is safe for
    every use in the corpus. Properties that legitimately apply to several
    unrelated classes (pbo:hasRisk applies to strategies, operating models,
    projects and agreements; pbo:hasMetricValue applies to scenarios,
    properties and market claims) are given a general domain (pbo:Entity or
    owl:Thing left unstated) and constrained per target class in SHACL.
    Warnings from the validator about omitted domain/range are intentional and
    documented here.
  evidence: []
  affects: [ontology.ttl, shapes.ttl]
  date: "2026-09-14"
153
- id: DEC-010
  topic: naming_iri_policy
  decision: camelcase_hash_namespace
  status: accepted
  rationale: >
    Base IRI https://ontology.property.local/pbo# with UpperCamelCase classes,
    lowerCamelCase properties, and SKOS concepts under scheme-prefixed local
    names (e.g. pbo:OperatingModel_MasterLease). Individuals used as fixtures
    use the prefix "ex" within the same namespace but are only in instances.ttl.
    The .local host signals that the namespace is not yet published; a
    persistent namespace should be chosen before any "released" version.
  evidence: []
  affects: [all artifacts]
  date: "2026-09-14"
168
- id: DEC-011
  topic: temporal_validity
  decision: validity_dates_on_authorisations_agreements_and_rules
  status: accepted
  rationale: >
    Tax rules change on 1 July 2027 with a 12 May 2026 grandfathering cut-off;
    Victorian smoke-alarm and rent-increase rules changed on 25 November 2025;
    the short-stay levy began 1 January 2025; foreign-buyer restrictions run
    1 April 2025 to 31 March 2027. pbo:effectiveFrom / pbo:effectiveUntil /
    pbo:cutoffDate datatype properties are placed on pbo:RegulatoryRule,
    pbo:Authorisation and pbo:Agreement. OWL-Time intervals are not imported;
    xsd:date literals are sufficient for CQ-012.
  evidence: [EV-130, EV-131, EV-132]
  affects: [TERM-RegulatoryRule, CQ-012]
  date: "2026-09-14"
184
- id: DEC-012
  topic: source_authority_ranking
  decision: authority_by_source_type_not_polish
  status: accepted
  rationale: >
    Authority levels in sources.yaml follow the category syntheses' own evidence
    notes: government/regulator pages (ATO, RTA, Business Queensland) are
    authoritative; the academic paper (Chartres 2017) is primary research; the
    two deep-research reports are secondary syntheses with dated citations;
    industry articles, vendor pages, investment offers and forum threads are
    illustrative or secondary. Promotional yield claims are never accepted as
    domain truth; they are catalogued as claims.
  evidence: []
  affects: [sources.yaml, evidence.jsonl]
  date: "2026-09-14"
200
- id: DEC-013
  topic: data_source_modelling
  decision: include_data_sources_as_information_resources
  status: accepted
  rationale: >
    The data-sources report is part of the corpus and the intended platform
    needs to know which dataset supplies which attribute. pbo:DataSource and
    pbo:Dataset are modelled as information resources (subclasses of
    pbo:InformationArtefact) with publisher, access tier (SKOS), refresh cadence,
    licence and pbo:suppliesAttribute links to pbo:PropertyAttribute concepts.
    Dataset internals (fields, geometries) are out of scope.
  evidence: [EV-140, EV-141]
  affects: [TERM-DataSource, CQ-009]
  date: "2026-09-14"
215
- id: DEC-014
  topic: jurisdiction_modelling
  decision: jurisdiction_individuals_with_containment
  status: accepted
  rationale: >
    Jurisdictions (Australia, Queensland, Victoria, NSW, WA, SA, Brisbane LGA,
    Logan LGA, Greater Melbourne) are named individuals of pbo:Jurisdiction in
    instances.ttl with pbo:withinJurisdiction containment, because the corpus
    names them as particulars and CQs filter by them. Foreign jurisdictions
    (Spain, Canada, Sweden, UK, US) exist only as source-context individuals.
  evidence: [EV-090, EV-095]
  affects: [TERM-Jurisdiction, instances.ttl]
  date: "2026-09-14"
229
- id: DEC-015
  topic: shacl_scope
  decision: shacl_for_record_completeness_only
  status: accepted
  rationale: >
    SHACL shapes require completeness for records the platform will store
    (FinancialScenario must declare its assumptions; Authorisation must have a
    jurisdiction, type and status; Agreement must have at least two
    participations; MetricValue must have a metric and a numeric value;
    OccupancyThreshold must have kind, comparator and value). Shapes do not
    encode domain truths such as "every rooming house has four or more
    residents", because sources disagree and exemptions exist.
  evidence: []
  affects: [shapes.ttl]
  date: "2026-09-14"
245
- id: DEC-016
  topic: synthesis_documents_as_sources
  decision: synthesis_documents_are_secondary_sources
  status: accepted
  rationale: >
    The seven category summaries, seven combined source references and two
    deep-research reports were compiled on 14 September 2026 from the raw
    sources plus (for the reports) external citations not present in the
    corpus. They are registered as secondary sources with their own IDs. Claims
    that appear only in a synthesis (e.g. Queensland residential-service
    accreditation levels, Victorian Clause 52.23 limits, negative-gearing
    reform dates) are recorded with support "explicit" against the synthesis
    but flagged in notes as not independently verifiable from the raw corpus.
  evidence: []
  affects: [sources.yaml, evidence.jsonl]
  date: "2026-09-14"