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#description-of-the-inetnum-object [3[ https://www.ripe.net/publications/docs/ripe-826/#70-types-of-address-space cheers denis
----- To unsubscribe from this mailing list or change your subscription options, please visit: https://mailman.ripe.net/mailman3/lists/db-wg.ripe.net/ As we have migrated to Mailman 3, you will need to create an account with the email matching your subscription before you can change your settings. More details at: https://www.ripe.net/membership/mail/mailman-3-migration/
