Clarification of Database documentation
Colleagues Some documentation issues were raised during a discussion of contact methods. They have nothing really to do with the issue of contacts so I have started a new thread on the documentation. It is not the most urgent issue regarding the RIPE Database so you may not care about any of this. But documentation should be correct or it is a waste of time having it. If no one comments, maybe the chairs can pass judgement. Three issues are raised here: -Attribute properties -Description of AGGREGATED-BY-LIR -Missing attribute Attribute properties For years we only described attributes as mandatory, optional or generated. But there are some attributes that do not exactly fit any of these categories. Mandatory means that every instance of this object type must have this attribute present. Optional means it is entirely your choice if you include it or not. Some attributes sit in between these two options. They don't need to be in every instance of the objects, but sometimes it is not your choice to leave it out. There are business rules built into the software that determine when certain attributes must be present or if you can ignore it. Examples include abuse-c and org. In most instances of an INETNUM object the org attribute is optional. But if it is an allocation, then it must be included. So it is not truly mandatory or optional. When I re-wrote the database documentation in 2014 I tried to cover this middle ground giving these attributes the property of being 'required' [1]. But as Ed just pointed out, the word 'required' suggests it is 'mandatory'. Certainly for a non native English speaker it is easy to confuse these meanings. So it is not the best word to use. The only word I can think of that might reflect the true meaning of these attributes is 'variable'. Sometimes it must be there, sometimes you can choose. There will be another document or policy that explains the business rules that determine how it is used. So unless someone has a better suggestion for naming this attribute property, I recommend that we adopt 'variable' in the documentation and in the templates returned by a whois query with -t and -v. Description of AGGREGATED-BY-LIR This is described in both the database documentation [2] and in the address policy [3]. Neither is an accurate and clear description and they are both different. In the address policy it says "The purpose and the contact details must be consistent throughout the whole assignment.". This confuses the terms 'aggregation' and 'assignments'. An aggregation is a collection of 'multiple' assignments. So you must either refer to the aggregation or the collection of assignments.You cannot refer to a single assignment. This is not just splitting hairs. For a non native English speaker new to the database, they are reading this to try to work out what this means. The current wording suggests the aggregation represents a single block of assigned address space, rather than a collection of multiple address blocks, possibly of different sizes. The purpose of an assignment is not publicly defined or documented anywhere. What is the purpose of a block of assigned address space? Can it be 'used by an End User's public network' or 'used by the LIR for their own infrastructure'? But then these are two different purposes. So by definition you should not be able to aggregate a mix of End User's address space with an LIR's own infrastructure. Is that the case? How does anyone outside of the LIR know? Should the purpose be documented in a remarks attribute? Should an aggregation have a "purpose:" attribute? It seems like there was such a rush to make individual assignments optional, the actual details of the aggregation were not very well thought through. What does "the contact details must be consistent" mean? All the assignments have a tech-c? All the tech-c references are to a ROLE object or a PERSON object? They all include an email address? They all refer to the same ROLE object? All the different ROLE objects reference the same email address? It is not good enough to say "but we all know what it means". A new LIR, new to the policy documents, new to the database may not know what this means. That is why they are reading it. There is no explicit mention that the multiple assignments can all be of different sizes. Unless the "assignment-size:" attribute is included. Is it sufficient for all these details to be explained in the RIPE Database documentation, that is only advisory? Possibly leaving the policy statement so vague that it is easy to misunderstand or misinterpret. Either way, all of these points need to be explained, somewhere. I haven't even touched on rules that should have so obviously been documented somewhere. For example, if aggregations are created retrospectively, the boundary between aggregations within a single allocation must match the boundaries of the encompassed assignments. If the assignments are deleted before creating the aggregations then the software cannot enforce this and there is no way for anyone to verify this was done. The whole concept of aggregation was badly specified. But that is another story... Missing attribute There is no mention in the documentation of the INETNUM or INET6NUM attribute 'prefixlen'. References [1] https://docs.db.ripe.net/RIPE-Database-Structure/Attribute-Properties [2] https://docs.db.ripe.net/RPSL-Object-Types/Descriptions-of-Primary-Objects#d... [3[ https://www.ripe.net/publications/docs/ripe-826/#70-types-of-address-space cheers denis
On Tue, Sep 30, 2025 at 02:31:30AM +0200, denis walker wrote: Hi Denis,
So unless someone has a better suggestion for naming this attribute property, I recommend that we adopt 'variable' in the documentation and in the templates returned by a whois query with -t and -v.
What about 'case-dependent'? Best, Piotr -- Piotr Strzyżewski
Hi Piotr I think many people would automatically interpret that as meaning upper or lower case. Cheers Denis On Tue, 30 Sept 2025, 14:38 Piotr Strzyzewski, <piotr@internetsailor.net> wrote:
On Tue, Sep 30, 2025 at 02:31:30AM +0200, denis walker wrote:
Hi Denis,
So unless someone has a better suggestion for naming this attribute property, I recommend that we adopt 'variable' in the documentation and in the templates returned by a whois query with -t and -v.
What about 'case-dependent'?
Best, Piotr
-- Piotr Strzyżewski
Hi, Just picking the item that is easiest to bike shed...
So unless someone has a better suggestion for naming this attribute property, I recommend that we adopt 'variable' in the documentation and in the templates returned by a whois query with -t and -v.
It sounds to me like these attributes are ‘conditionally mandatory’, or perhaps just ‘conditional’. Rob
Hi Rob I think 'conditional' is the ideal word for it. So it's either mandatory, optional or conditional. Cheers Denis On Tue, 30 Sept 2025, 14:57 Rob Evans, <rhe@nosc.ja.net> wrote:
Hi,
Just picking the item that is easiest to bike shed...
So unless someone has a better suggestion for naming this attribute property, I recommend that we adopt 'variable' in the documentation and in the templates returned by a whois query with -t and -v.
It sounds to me like these attributes are ‘conditionally mandatory’, or perhaps just ‘conditional’.
Rob
Dear Denis, colleagues,
On 30 Sep 2025, at 02:31, denis walker <ripedenis@gmail.com> wrote:
Colleagues
Some documentation issues were raised during a discussion of contact methods. They have nothing really to do with the issue of contacts so I have started a new thread on the documentation. It is not the most urgent issue regarding the RIPE Database so you may not care about any of this. But documentation should be correct or it is a waste of time having it. If no one comments, maybe the chairs can pass judgement.
Three issues are raised here: -Attribute properties -Description of AGGREGATED-BY-LIR -Missing attribute
Attribute properties ...
As suggested in this thread, unless there are any objections, the DB team will implement "conditional" for an attribute in the object template, in addition to "mandatory", "optional" and "generated". A "conditional" attribute can be mandatory depending on the business rules, we will add a link to the documentation : https://docs.db.ripe.net/Database-Support/Database-Business-Rules
Description of AGGREGATED-BY-LIR This is described in both the database documentation [2] and in the address policy [3]. Neither is an accurate and clear description and they are both different.
In the address policy it says "The purpose and the contact details must be consistent throughout the whole assignment.". This confuses the terms 'aggregation' and 'assignments'. An aggregation is a collection of 'multiple' assignments. So you must either refer to the aggregation or the collection of assignments.You cannot refer to a single assignment. This is not just splitting hairs. For a non native English speaker new to the database, they are reading this to try to work out what this means. The current wording suggests the aggregation represents a single block of assigned address space, rather than a collection of multiple address blocks, possibly of different sizes.
We will re-write this section of the documentation.
The purpose of an assignment is not publicly defined or documented anywhere. What is the purpose of a block of assigned address space? Can it be 'used by an End User's public network' or 'used by the LIR for their own infrastructure'? But then these are two different purposes. So by definition you should not be able to aggregate a mix of End User's address space with an LIR's own infrastructure. Is that the case? How does anyone outside of the LIR know? Should the purpose be documented in a remarks attribute? Should an aggregation have a "purpose:" attribute? It seems like there was such a rush to make individual assignments optional, the actual details of the aggregation were not very well thought through.
What does "the contact details must be consistent" mean? All the assignments have a tech-c? All the tech-c references are to a ROLE object or a PERSON object? They all include an email address? They all refer to the same ROLE object? All the different ROLE objects reference the same email address? It is not good enough to say "but we all know what it means". A new LIR, new to the policy documents, new to the database may not know what this means. That is why they are reading it.
I appreciate any feedback on these points from the community. We will re-write this section to make it clearer.
There is no explicit mention that the multiple assignments can all be of different sizes. Unless the "assignment-size:" attribute is included.
We will update the documentation to make this clear.
Is it sufficient for all these details to be explained in the RIPE Database documentation, that is only advisory? Possibly leaving the policy statement so vague that it is easy to misunderstand or misinterpret. Either way, all of these points need to be explained, somewhere.
I think the DB documentation needs to clearly explain the intention of the policy, including examples, to help the user to comply with the policy. We can also include links back to the policy text.
I haven't even touched on rules that should have so obviously been documented somewhere. For example, if aggregations are created retrospectively, the boundary between aggregations within a single allocation must match the boundaries of the encompassed assignments. If the assignments are deleted before creating the aggregations then the software cannot enforce this and there is no way for anyone to verify this was done. The whole concept of aggregation was badly specified. But that is another story...
We will improve the documentation where it's deficient. I also encourage the community to contribute improvements via the documentation repository : https://github.com/RIPE-NCC/ripe-database-documentation
Missing attribute There is no mention in the documentation of the INETNUM or INET6NUM attribute 'prefixlen'.
Apologies for the omission, we will add the "prefixlen" attribute to the documentation ( https://datatracker.ietf.org/doc/draft-ietf-opsawg-prefix-lengths/ ). Regards Ed Shryane RIPE NCC
Hello Denis, Just a small update in reply to your earlier mail regarding documentation.
On 30 Sep 2025, at 02:31, denis walker <ripedenis@gmail.com> wrote:
Colleagues
Some documentation issues were raised during a discussion of contact methods. They have nothing really to do with the issue of contacts so I have started a new thread on the documentation. It is not the most urgent issue regarding the RIPE Database so you may not care about any of this. But documentation should be correct or it is a waste of time having it. If no one comments, maybe the chairs can pass judgement.
Three issues are raised here: -Attribute properties
The DB team are working on the implementation of the "conditional" attribute state.
-Description of AGGREGATED-BY-LIR
I have updated the AGGREGATED-BY-LIR description including "assignment-size:" https://github.com/RIPE-NCC/ripe-database-documentation/pull/31 And updated the website: https://docs.db.ripe.net/RPSL-Object-Types/Descriptions-of-Primary-Objects To address your feedback completely will take some more time. I will ask for a draft review before publishing.
-Missing attribute
Also added the "prefixlen:" attribute: https://github.com/RIPE-NCC/ripe-database-documentation/pull/30 Regards Ed Shryane RIPE NCC
participants (4)
-
denis walker -
Edward Shryane -
Piotr Strzyzewski -
Rob Evans