docs: internals: Add system fields

[sakshamarora1]

No description provided.

[carlinmack]

LGTM! only one thing I'd change

[carlinmack]

I would remove this heading as the following information doesn't need it

[fenekku]

+1

[carlinmack]

nice example!

[fenekku]

Lots of little comments, but honestly this is such useful documentation. System fields are by far the part of the code base that I've found the most unpenetrable and having documentation that lays it all out is wonderful. Thanks for all that.

[fenekku]

Probably best to go one of two ways completely:

Suggested change

	# System Fields
	# System fields

(I slightly prefer this one because it allows us to talk about the concept separate from the Python class)

or

Suggested change

	# System Fields
	# SystemFields

. And then stick with that throughtout the text and filenaming. Singular or plural too should be settled on.

[fenekku]

so .e.g.,

Suggested change

	SystemFields is a powerful abstraction layer in InvenioRDM that provides managed access to record data through Python descriptors. It bridges the gap between the raw JSON dictionary structure of records and object-oriented Python interfaces, enabling sophisticated data management, validation, and integration with related objects.
	System fields are a powerful abstraction layer in InvenioRDM that provide managed access to record data through Python descriptors. They bridge the gap between the raw JSON dictionary structure of records and object-oriented Python interfaces, enabling sophisticated data management, validation, and integration with related objects.

[fenekku]

Suggested change

	At its core, SystemFields transforms simple attribute access (`record.title`) into complex operations that can involve:
	At its core, System fields transform simple attribute access (`record.title`) into complex operations that can involve:

[fenekku]

(to prefer active voice and relate it to the code on display)

Suggested change

	# When you access record.title, SystemField.__get__ is called
	# When you set record.title = "New Title", SystemField.__set__ is called
	# record.title calls ConstantField.__get__
	# record.title = "New Title" calls ConstantField.__set__

[fenekku]

+1

[fenekku]

Suggested change

	class TimestampField(SystemField):
	"""A field that tracks creation and modification times."""
	from invenio_records.api import Record
	from invenio_records.systemfields import SystemField, SystemFieldsMixin
	class TimestampField(SystemField):
	"""A field that tracks creation and modification times."""

[fenekku]

Suggested change

	Relations are specialized SystemFields that manage connections between records and external entities (other records, database models, APIs, etc.).
	Relations are specialized SystemFields that manage connections between records and other entities (other records, database models, APIs, etc.).

[fenekku]

Can we make explicit the relationship between these classes and the concrete code below or concrete code in general? For example, RelationsField is invenio_records.systemfields.relations.RelationsField, a Relation class can be PKRelation and so on...

Mapping Class -> Mapping Classes

[fenekku]

They are meant to be, but there is no enforcement - it's up to the developer. So I guess it's more a matter of advising developers to respect that principle 😁 : . Not sure if any example would help for that. Perhaps a note block instead? And perhaps move it to the "Best practices" section?

[fenekku]

This section is for maintainers and core developers rather than instance operators:

• we can either skip the Conclusion section completely (not really an essay or an AI answer right? haha)
• Or

Suggested change

	By following these patterns and best practices, you can create robust, maintainable SystemFields that enhance your InvenioRDM instance's capabilities while maintaining clean, readable code.
	By following these patterns and best practices, you can create robust, maintainable System fields that enhance InvenioRDM's capabilities while maintaining clean, readable code.