YANG Data Model for the Precision Time Protocol (PTP)
Extracted elements (25)
The concept of a 'PTP instance' (an OC or BC represented by a specific data set operating in exactly one domain) is introduced to clarify how multiple PTP domains are organized within a single device; IEEE Std 1588-2008 subclause 7.1 allows multiple domains but its data set organization was ambiguous. The instance number has no usage within PTP messages.
The IEEE Std 1588-2008 'portIdentity' struct is decomposed across the YANG model: portIdentity.portNumber is the list key in port-ds-list, while portIdentity.clockIdentity is accessed via ../../default-ds/clock-identity, avoiding duplication while preserving the full identity.
The YANG module was developed in the IETF TICTOC WG rather than the IEEE 1588 WG because IEEE 1588 provides a clear information model (data sets) but YANG expertise resided in IETF; an Appendix documents the planned future transfer to IEEE once the IEEE 1588 WG gains YANG expertise.
Transparent clock data sets ('transparent-clock-default-ds' and 'transparent-clock-port-ds-list') are placed as singletons at the root level of the managed product, reflecting how most TC products interpret IEEE Std 1588-2008 subclauses 8.3.1 and 10.1, rather than per-instance.
The ietf-ptp YANG module is intended to be importable by profile-specific modules (e.g., telecom or automotive PTP profiles) using YANG 'import' and 'augment', enabling extensibility while maintaining a common base derived from IEEE Std 1588-2008 data sets.
When YANG work is eventually transferred to the IEEE 1588 WG, the module namespace root changes from IETF (urn:ietf:params:xml:ns:yang:ietf-ptp) to IEEE (e.g., urn:ieee:Std:1588:yang:ieee1588-ptp), but the prefix 'ptp' is preserved to minimize migration impact for importing modules.
A product conforming to a profile standard SHOULD 'import' the profile's YANG module and use YANG 'augment' to add any product-specific enhancements.
A profile standard based on IEEE Std 1588-2008 that creates a dedicated YANG module SHOULD use YANG 'import' to import the ietf-ptp module as its foundation, and SHOULD use YANG 'augment' to add profile-specific enhancements.
When a configurable IEEE Std 1588 data set member needs to be treated as read-only in a YANG implementation, an implementation SHOULD return a warning on write or use the YANG deviation mechanism as described in RFC 7950 Section 7.20.3.
When the IEEE Std 1588 standard is revised and the YANG module is updated, the YANG 'revision' statement MUST be used to indicate changes to the YANG module.
The 'current-ds' container exposes runtime synchronization state: steps-removed (uint16, default 0), offset-from-master (time-interval-type), and mean-path-delay (time-interval-type), as specified in IEEE Std 1588-2008 subclause 8.2.2.
The 'default-ds' container holds core clock configuration including two-step-flag (boolean), clock-identity (read-only, 8-byte binary), number-ports (uint16), clock-quality (class, accuracy, offsetScaledLogVariance), priority1, priority2, domain-number, and slave-only flag, as specified in IEEE Std 1588-2008 subclause 8.2.1.
The 'delay-mechanism-enumeration' typedef defines three values: e2e (1, delay request-response mechanism), p2p (2, peer delay mechanism), and disabled (254, no delay mechanism), per IEEE Std 1588-2008 clause 8.2.5.4.4.
The ietf-ptp YANG module defines the top-level 'ptp' container with an 'instance-list' keyed by 'instance-number', grouping all PTP data sets (default-ds, current-ds, parent-ds, time-properties-ds, port-ds-list) for each Ordinary or Boundary Clock instance, plus 'transparent-clock-default-ds' and 'transparent-clock-port-ds-list' at the root for Transparent Clocks.
The 'parent-ds' container identifies the master clock: parent-port-identity (clockIdentity + portNumber), parent-stats boolean, observed-parent-offset-scaled-log-variance (uint16, default 65535), observed-parent-clock-phase-change-rate (int32), grandmaster-identity, grandmaster-clock-quality, grandmaster-priority1, and grandmaster-priority2, per IEEE Std 1588-2008 subclause 8.2.3.
The 'port-ds-list' list (keyed by port-number) contains per-port state and configuration: port-state, underlying-interface (RFC 8343 ref), log-min-delay-req-interval, peer-mean-path-delay, log-announce-interval, announce-receipt-timeout, log-sync-interval, delay-mechanism, log-min-pdelay-req-interval, and version-number, per IEEE Std 1588-2008 subclause 8.2.5.
The 'time-properties-ds' container carries UTC/timescale metadata: current-utc-offset-valid, current-utc-offset (int16, conditional on valid flag), leap59, leap61, time-traceable, frequency-traceable, ptp-timescale, and time-source (uint8), per IEEE Std 1588-2008 subclause 8.2.4.
The 'transparent-clock-default-ds' singleton container holds TC-wide configuration: clock-identity (read-only), number-ports, delay-mechanism, and primary-domain (uint8, default 0), per IEEE Std 1588-2008 subclause 8.3.2.
RFC 8575 registers the URI 'urn:ietf:params:xml:ns:yang:ietf-ptp' in the IETF XML Registry (RFC 3688) as an XML namespace for the ietf-ptp YANG module.
RFC 8575 registers the YANG module 'ietf-ptp' with namespace 'urn:ietf:params:xml:ns:yang:ietf-ptp' and prefix 'ptp' in the YANG Module Names registry (RFC 6020).
NETCONF access to the PTP YANG module requires SSH (mandatory-to-implement per RFC 6242) as the secure transport; RESTCONF requires HTTPS with TLS (RFC 8446). General security considerations for time protocols are referenced in RFC 7384.
The Network Configuration Access Control Model (NACM, RFC 8341) must be used to restrict write access to the sensitive PTP data nodes (/ptp/instance-list, /ptp/transparent-clock-default-ds, /ptp/transparent-clock-port-ds-list). Unauthorized write operations can cause clock loss, accuracy degradation, or complete synchronization network failure.
The 'port-state-enumeration' typedef defines nine PTP port states: initializing (1), faulty (2), disabled (3), listening (4), pre-master (5), master (6), passive (7), uncalibrated (8), and slave (9), per IEEE Std 1588-2008 clauses 8.2.5.3.1 and 9.2.5.
The 'clock-identity-type' typedef is a binary value of exactly 8 bytes, used to uniquely identify a PTP clock, per IEEE Std 1588-2008 clause 5.3.4.
The 'time-interval-type' typedef is an int64 representing time in nanoseconds multiplied by 2^16, matching the TimeInterval definition in IEEE Std 1588-2008 clause 5.3.2.